New figure illustrating multiple transformations across faces.

git-svn-id: http://svn.cactuscode.org/arrangements/CactusBase/SymBase/trunk@23 906471b6-c639-44d1-9ea0-3e3d6879f074

3 files changed, 757 insertions, 40 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 9efc3ad..1fe87a2 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -118,6 +118,28 @@ query this thorn about the set of faces that have symmetry boundary
 conditions and should not apply the physical boundary condition there.
 
 
+\begin{figure}[tb]
+\begin{center}
+\includegraphics[scale=.833,clip=true]{fig/faces.eps}
+\end{center}
+\caption[Symmetry transformations across faces] {
+	A SymBase symmetry transformation can incorporate multiple 
+	geometric symetry transformations, one for each registered 
+	symmetry face.
+
+	In cases of a reflection symmetry across a component face, 
+	the data may be stored only on one side of the face.
+	To get data values at a point on the other side of the face, the
+	point is transformed (reflected, in this case) across the face.
+	
+	Here, a point $x$ is transformed to point $x'$ by transformation
+	$A$, and then to point $x''$ by transformation $B$.  Data is
+	only actually stored for point $x''$.
+}
+\label{SymBase.faces}
+\end{figure}
+
+
 
 \section{Registering Symmetry Conditions}
 
@@ -327,54 +349,55 @@ works as follows:
 \item If no faces are flagged, SymBase calls the driver's aliased
   function \texttt{DriverInterpolate}, which performs the actual
   interpolation.  This ends the chain of recursive calls.
-\item If there are faces with symmetry conditions flagged, SymBase
-  chooses one such face, and then calls this face's symmetry
-  condition's ``symmetry interpolation'' routine, passing along all
-  arguments.
-\item The ``symmetry interpolation'' routine maps the coordinates into
-  the domain by applying the symmetry condition for this face.  It
-  then removes the flag for the corresponding face, and calls
-  \texttt{SymmetryInterpolateFaces}, passing along the arguments with
-  the changed interpolation locations.
-\item After the actual interpolation has happened in the driver, the
-  recursive call will return.  The ``symmetry interpolation'' routine
-  then examines the tensor types of the interpolated quantities and
-  un-maps the values back onto their original locations.  That is,
-  e.g., after a reflection on the lower $x$-boundary, $x$-components
-  of vectors need their sign changed.
-\item The chain of recursive calls unravels until the call to
-  \texttt{CCTK\_InterpGridArrays} returns.
-\end{enumerate}
+	\item If there are faces with symmetry conditions flagged, SymBase
+	  chooses one such face, and then calls this face's symmetry
+	  condition's ``symmetry interpolation'' routine, passing along all
+	  arguments.
+	\item The ``symmetry interpolation'' routine maps the coordinates into
+	  the domain by applying the symmetry condition for this face.  It
+	  then removes the flag for the corresponding face, and calls
+	  \texttt{SymmetryInterpolateFaces}, passing along the arguments with
+	  the changed interpolation locations.
+	\item After the actual interpolation has happened in the driver, the
+	  recursive call will return.  The ``symmetry interpolation'' routine
+	  then examines the tensor types of the interpolated quantities and
+	  un-maps the values back onto their original locations.  That is,
+	  e.g., after a reflection on the lower $x$-boundary, $x$-components
+	  of vectors need their sign changed.
+	\item The chain of recursive calls unravels until the call to
+	  \texttt{CCTK\_InterpGridArrays} returns.
+	\end{enumerate}
+	This mechanism has thus four players:
+	\begin{itemize}
+	\item The driver forwards the call to SymBase so that the list of
+	  interpolation points can be mapped into the domain.
+	\item Thorn SymBase controls which symmetry conditions perform this
+	  mapping on which faces.
+\item Each symmetry boundary condition has to register a ``symmetry
+  interpolation'' routine that first maps the points into the domain,
+  then calls SymBase recursively, and finally corrects the tensor
+  types of the interpolated quantities.
+\item Finally, the user calls \texttt{CCTK\_InterpGridArrays} as before, and
+  everything happens transparently for her.
+\end{itemize}
+
 \begin{figure}[tb]
 \begin{center}
 \includegraphics[scale=.833,clip=true]{fig/recursion.eps}
 \end{center}
 \caption[Symmetry interpolation] {
-  The recursive calls involved in symmety interpolation.
-  Values of grid functions $a$ at global cartesian coordinates $x$ are 
-  calculated by nested calls to the symmetry interpolators, which first
-  apply the symmetry transformation to the coordinates.  When all
-  the symmetries have been applied, the local interpolator is called,
-  producing the interpolation of grid function values in the local basis.
-  As the symmetry interpolators return, they apply the inverse basis
-  transformation to the interpolated grid function values.
+	  The recursive calls involved in symmety interpolation.
+	  Values of grid functions $a$ at global cartesian coordinates $x$ are 
+	  calculated by nested calls to the symmetry interpolators, which first
+	  apply the symmetry transformation to the coordinates.  When all
+	  the symmetries have been applied, the local interpolator is called,
+	  producing the interpolation of grid function values in the local basis.
+	  As the symmetry interpolators return, they apply the inverse basis
+	  transformation to the interpolated grid function values.
 }
-\label{SymBase_recursion}
+\label{SymBase.recursion}
 \end{figure}
 
-This mechanism has thus four players:
-\begin{itemize}
-\item The driver forwards the call to SymBase so that the list of
-  interpolation points can be mapped into the domain.
-\item Thorn SymBase controls which symmetry conditions perform this
-  mapping on which faces.
-\item Each symmetry boundary condition has to register a ``symmetry
-  interpolation'' routine that first maps the points into the domain,
-  then calls SymBase recursively, and finally corrects the tensor
-  types of the interpolated quantities.
-\item Finally, the user calls \texttt{CCTK\_InterpGridArrays} as before, and
-  everything happens transparently for her.
-\end{itemize}
 
 
 
diff --git a/doc/fig/faces.eps b/doc/fig/faces.eps
new file mode 100644
index 0000000..0dcbb63
--- /dev/null
+++ b/doc/fig/faces.eps
@@ -0,0 +1,631 @@
+%!PS-Adobe-2.0 EPSF-2.0
+%%Title: faces.fig
+%%Creator: fig2dev Version 3.2 Patchlevel 5-alpha5
+%%CreationDate: Sat Aug 13 21:51:34 2005
+%%For: swhite@Xi (Steve White,,,)
+%%BoundingBox: 0 0 251 251
+%Magnification: 1.0000
+%%EndComments
+/MyAppDict 100 dict dup begin def
+/$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 251 moveto 0 0 lineto 251 0 lineto 251 251 lineto closepath clip newpath
+0.8 250.2 translate
+1 -1 scale
+
+% This junk string is used by the show operators
+/PATsstr 1 string def
+/PATawidthshow { 	% cx cy cchar rx ry string
+  % Loop over each character in the string
+  {  % cx cy cchar rx ry char
+    % Show the character
+    dup				% cx cy cchar rx ry char char
+    PATsstr dup 0 4 -1 roll put	% cx cy cchar rx ry char (char)
+    false charpath		% cx cy cchar rx ry char
+    /clip load PATdraw
+    % Move past the character (charpath modified the
+    % current point)
+    currentpoint			% cx cy cchar rx ry char x y
+    newpath
+    moveto			% cx cy cchar rx ry char
+    % Reposition by cx,cy if the character in the string is cchar
+    3 index eq {			% cx cy cchar rx ry
+      4 index 4 index rmoveto
+    } if
+    % Reposition all characters by rx ry
+    2 copy rmoveto		% cx cy cchar rx ry
+  } forall
+  pop pop pop pop pop		% -
+  currentpoint
+  newpath
+  moveto
+} bind def
+/PATcg {
+  7 dict dup begin
+    /lw currentlinewidth def
+    /lc currentlinecap def
+    /lj currentlinejoin def
+    /ml currentmiterlimit def
+    /ds [ currentdash ] def
+    /cc [ currentrgbcolor ] def
+    /cm matrix currentmatrix def
+  end
+} bind def
+% PATdraw - calculates the boundaries of the object and
+% fills it with the current pattern
+/PATdraw {			% proc
+  save exch
+    PATpcalc			% proc nw nh px py
+    5 -1 roll exec		% nw nh px py
+    newpath
+    PATfill			% -
+  restore
+} bind def
+% PATfill - performs the tiling for the shape
+/PATfill { % nw nh px py PATfill -
+  PATDict /CurrentPattern get dup begin
+    setfont
+    % Set the coordinate system to Pattern Space
+    PatternGState PATsg
+    % Set the color for uncolored pattezns
+    PaintType 2 eq { PATDict /PColor get PATsc } if
+    % Create the string for showing
+    3 index string		% nw nh px py str
+    % Loop for each of the pattern sources
+    0 1 Multi 1 sub {		% nw nh px py str source
+	% Move to the starting location
+	3 index 3 index		% nw nh px py str source px py
+	moveto			% nw nh px py str source
+	% For multiple sources, set the appropriate color
+	Multi 1 ne { dup PC exch get PATsc } if
+	% Set the appropriate string for the source
+	0 1 7 index 1 sub { 2 index exch 2 index put } for pop
+	% Loop over the number of vertical cells
+	3 index 		% nw nh px py str nh
+	{			% nw nh px py str
+	  currentpoint		% nw nh px py str cx cy
+	  2 index oldshow	% nw nh px py str cx cy
+	  YStep add moveto	% nw nh px py str
+	} repeat		% nw nh px py str
+    } for
+    5 { pop } repeat
+  end
+} bind def
+
+% PATkshow - kshow with the current pattezn
+/PATkshow {			% proc string
+  exch bind			% string proc
+  1 index 0 get			% string proc char
+  % Loop over all but the last character in the string
+  0 1 4 index length 2 sub {
+				% string proc char idx
+    % Find the n+1th character in the string
+    3 index exch 1 add get	% string proc char char+1
+    exch 2 copy			% strinq proc char+1 char char+1 char
+    % Now show the nth character
+    PATsstr dup 0 4 -1 roll put	% string proc chr+1 chr chr+1 (chr)
+    false charpath		% string proc char+1 char char+1
+    /clip load PATdraw
+    % Move past the character (charpath modified the current point)
+    currentpoint newpath moveto
+    % Execute the user proc (should consume char and char+1)
+    mark 3 1 roll		% string proc char+1 mark char char+1
+    4 index exec		% string proc char+1 mark...
+    cleartomark			% string proc char+1
+  } for
+  % Now display the last character
+  PATsstr dup 0 4 -1 roll put	% string proc (char+1)
+  false charpath		% string proc
+  /clip load PATdraw
+  neewath
+  pop pop			% -
+} bind def
+% PATmp - the makepattern equivalent
+/PATmp {			% patdict patmtx PATmp patinstance
+  exch dup length 7 add		% We will add 6 new entries plus 1 FID
+  dict copy			% Create a new dictionary
+  begin
+    % Matrix to install when painting the pattern
+    TilingType PATtcalc
+    /PatternGState PATcg def
+    PatternGState /cm 3 -1 roll put
+    % Check for multi pattern sources (Level 1 fast color patterns)
+    currentdict /Multi known not { /Multi 1 def } if
+    % Font dictionary definitions
+    /FontType 3 def
+    % Create a dummy encoding vector
+    /Encoding 256 array def
+    3 string 0 1 255 {
+      Encoding exch dup 3 index cvs cvn put } for pop
+    /FontMatrix matrix def
+    /FontBBox BBox def
+    /BuildChar {
+	mark 3 1 roll		% mark dict char
+	exch begin
+	Multi 1 ne {PaintData exch get}{pop} ifelse  % mark [paintdata]
+	  PaintType 2 eq Multi 1 ne or
+	  { XStep 0 FontBBox aload pop setcachedevice }
+	  { XStep 0 setcharwidth } ifelse
+	  currentdict		% mark [paintdata] dict
+	  /PaintProc load	% mark [paintdata] dict paintproc
+	end
+	gsave
+	  false PATredef exec true PATredef
+	grestore
+	cleartomark		% -
+    } bind def
+    currentdict
+  end				% newdict
+  /foo exch			% /foo newlict
+  definefont			% newfont
+} bind def
+% PATpcalc - calculates the starting point and width/height
+% of the tile fill for the shape
+/PATpcalc {	% - PATpcalc nw nh px py
+  PATDict /CurrentPattern get begin
+    gsave
+	% Set up the coordinate system to Pattern Space
+	% and lock down pattern
+	PatternGState /cm get setmatrix
+	BBox aload pop pop pop translate
+	% Determine the bounding box of the shape
+	pathbbox			% llx lly urx ury
+    grestore
+    % Determine (nw, nh) the # of cells to paint width and height
+    PatHeight div ceiling		% llx lly urx qh
+    4 1 roll				% qh llx lly urx
+    PatWidth div ceiling		% qh llx lly qw
+    4 1 roll				% qw qh llx lly
+    PatHeight div floor			% qw qh llx ph
+    4 1 roll				% ph qw qh llx
+    PatWidth div floor			% ph qw qh pw
+    4 1 roll				% pw ph qw qh
+    2 index sub cvi abs			% pw ph qs qh-ph
+    exch 3 index sub cvi abs exch	% pw ph nw=qw-pw nh=qh-ph
+    % Determine the starting point of the pattern fill
+    %(px, py)
+    4 2 roll				% nw nh pw ph
+    PatHeight mul			% nw nh pw py
+    exch				% nw nh py pw
+    PatWidth mul exch			% nw nh px py
+  end
+} bind def
+
+% Save the original routines so that we can use them later on
+/oldfill	/fill load def
+/oldeofill	/eofill load def
+/oldstroke	/stroke load def
+/oldshow	/show load def
+/oldashow	/ashow load def
+/oldwidthshow	/widthshow load def
+/oldawidthshow	/awidthshow load def
+/oldkshow	/kshow load def
+
+% These defs are necessary so that subsequent procs don't bind in
+% the originals
+/fill	   { oldfill } bind def
+/eofill	   { oldeofill } bind def
+/stroke	   { oldstroke } bind def
+/show	   { oldshow } bind def
+/ashow	   { oldashow } bind def
+/widthshow { oldwidthshow } bind def
+/awidthshow { oldawidthshow } bind def
+/kshow 	   { oldkshow } bind def
+/PATredef {
+  MyAppDict begin
+    {
+    /fill { /clip load PATdraw newpath } bind def
+    /eofill { /eoclip load PATdraw newpath } bind def
+    /stroke { PATstroke } bind def
+    /show { 0 0 null 0 0 6 -1 roll PATawidthshow } bind def
+    /ashow { 0 0 null 6 3 roll PATawidthshow }
+    bind def
+    /widthshow { 0 0 3 -1 roll PATawidthshow }
+    bind def
+    /awidthshow { PATawidthshow } bind def
+    /kshow { PATkshow } bind def
+  } {
+    /fill   { oldfill } bind def
+    /eofill { oldeofill } bind def
+    /stroke { oldstroke } bind def
+    /show   { oldshow } bind def
+    /ashow  { oldashow } bind def
+    /widthshow { oldwidthshow } bind def
+    /awidthshow { oldawidthshow } bind def
+    /kshow  { oldkshow } bind def
+    } ifelse
+  end
+} bind def
+false PATredef
+% Conditionally define setcmykcolor if not available
+/setcmykcolor where { pop } {
+  /setcmykcolor {
+    1 sub 4 1 roll
+    3 {
+	3 index add neg dup 0 lt { pop 0 } if 3 1 roll
+    } repeat
+    setrgbcolor - pop
+  } bind def
+} ifelse
+/PATsc {		% colorarray
+  aload length		% c1 ... cn length
+    dup 1 eq { pop setgray } { 3 eq { setrgbcolor } { setcmykcolor
+  } ifelse } ifelse
+} bind def
+/PATsg {		% dict
+  begin
+    lw setlinewidth
+    lc setlinecap
+    lj setlinejoin
+    ml setmiterlimit
+    ds aload pop setdash
+    cc aload pop setrgbcolor
+    cm setmatrix
+  end
+} bind def
+
+/PATDict 3 dict def
+/PATsp {
+  true PATredef
+  PATDict begin
+    /CurrentPattern exch def
+    % If it's an uncolored pattern, save the color
+    CurrentPattern /PaintType get 2 eq {
+      /PColor exch def
+    } if
+    /CColor [ currentrgbcolor ] def
+  end
+} bind def
+% PATstroke - stroke with the current pattern
+/PATstroke {
+  countdictstack
+  save
+  mark
+  {
+    currentpoint strokepath moveto
+    PATpcalc				% proc nw nh px py
+    clip newpath PATfill
+    } stopped {
+	(*** PATstroke Warning: Path is too complex, stroking
+	  with gray) =
+    cleartomark
+    restore
+    countdictstack exch sub dup 0 gt
+	{ { end } repeat } { pop } ifelse
+    gsave 0.5 setgray oldstroke grestore
+  } { pop restore pop } ifelse
+  newpath
+} bind def
+/PATtcalc {		% modmtx tilingtype PATtcalc tilematrix
+  % Note: tiling types 2 and 3 are not supported
+  gsave
+    exch concat					% tilingtype
+    matrix currentmatrix exch			% cmtx tilingtype
+    % Tiling type 1 and 3: constant spacing
+    2 ne {
+	% Distort the pattern so that it occupies
+	% an integral number of device pixels
+	dup 4 get exch dup 5 get exch		% tx ty cmtx
+	XStep 0 dtransform
+	round exch round exch			% tx ty cmtx dx.x dx.y
+	XStep div exch XStep div exch		% tx ty cmtx a b
+	0 YStep dtransform
+	round exch round exch			% tx ty cmtx a b dy.x dy.y
+	YStep div exch YStep div exch		% tx ty cmtx a b c d
+	7 -3 roll astore			% { a b c d tx ty }
+    } if
+  grestore
+} bind def
+/PATusp {
+  false PATredef
+  PATDict begin
+    CColor PATsc
+  end
+} bind def
+
+% left45
+11 dict begin
+/PaintType 1 def
+/PatternType 1 def
+/TilingType 1 def
+/BBox [0 0 1 1] def
+/XStep 1 def
+/YStep 1 def
+/PatWidth 1 def
+/PatHeight 1 def
+/Multi 2 def
+/PaintData [
+  { clippath } bind
+  { 20 20 true [ 20 0 0 -20 0 20 ]
+	{<8020004010002008001004000802000401000200
+	8001004000802000401080200040100020080010
+	0400080200040100020080010040008020004010>}
+     imagemask } bind
+] def
+/PaintProc {
+	pop
+	exec fill
+} def
+currentdict
+end
+/P4 exch def
+
+% right45
+11 dict begin
+/PaintType 1 def
+/PatternType 1 def
+/TilingType 1 def
+/BBox [0 0 1 1] def
+/XStep 1 def
+/YStep 1 def
+/PatWidth 1 def
+/PatHeight 1 def
+/Multi 2 def
+/PaintData [
+  { clippath } bind
+  { 20 20 true [ 20 0 0 -20 0 20 ]
+	{<0040100080200100400200800401000802001004
+	0020080040100080200000401000802001004002
+	0080040100080200100400200800401000802000>}
+     imagemask } bind
+] def
+/PaintProc {
+	pop
+	exec fill
+} def
+currentdict
+end
+/P5 exch def
+
+% crosshatch45
+11 dict begin
+/PaintType 1 def
+/PatternType 1 def
+/TilingType 1 def
+/BBox [0 0 1 1] def
+/XStep 1 def
+/YStep 1 def
+/PatWidth 1 def
+/PatHeight 1 def
+/Multi 2 def
+/PaintData [
+  { clippath } bind
+  { 20 20 true [ 20 0 0 -20 0 20 ]
+	{<8020004050102088201104400a02800401000a02
+	8011044020882040501080200040501020882011
+	04400a02800401000a0280110440208820405010>}
+     imagemask } bind
+] def
+/PaintProc {
+	pop
+	exec fill
+} def
+currentdict
+end
+/P6 exch def
+
+/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
+% Polyline
+0 slj
+0 slc
+0.000 slw
+n 90 135 m 1980 135 l 1980 1980 l 90 1980 l
+ cp gs /PC [[1.00 1.00 1.00] [0.00 0.00 0.00]] def
+15.00 15.00 sc P5 [16 0 0 -16 6.00 9.00] PATmp PATsp ef gr PATusp 
+% Polyline
+n 1980 1980 m 3870 1980 l 3870 3870 l 1980 3870 l
+ cp gs /PC [[1.00 1.00 1.00] [0.00 0.00 0.00]] def
+15.00 15.00 sc P4 [16 0 0 -16 132.00 132.00] PATmp PATsp ef gr PATusp 
+% Polyline
+n 90 1980 m 1980 1980 l 1980 3870 l 90 3870 l
+ cp gs /PC [[1.00 1.00 1.00] [0.00 0.00 0.00]] def
+15.00 15.00 sc P6 [16 0 0 -16 6.00 132.00] PATmp PATsp ef gr PATusp 
+% Polyline
+2 slj
+7.500 slw
+gs  clippath
+1176 1062 m 1303 910 l 1245 862 l 1119 1014 l 1119 1014 l 1244 923 l 1176 1062 l cp
+eoclip
+n 1220 2923 m 1219 2922 l 1217 2920 l 1214 2917 l 1209 2912 l 1201 2904 l
+ 1191 2894 l 1179 2882 l 1164 2867 l 1148 2849 l 1129 2829 l
+ 1109 2807 l 1088 2783 l 1065 2757 l 1042 2729 l 1019 2699 l
+ 995 2669 l 972 2636 l 949 2603 l 927 2568 l 906 2531 l
+ 885 2493 l 866 2453 l 847 2411 l 831 2366 l 815 2319 l
+ 802 2269 l 790 2216 l 781 2161 l 774 2102 l 770 2041 l
+ 770 1978 l 773 1918 l 779 1859 l 787 1802 l 798 1746 l
+ 811 1692 l 825 1641 l 841 1591 l 858 1543 l 877 1498 l
+ 896 1454 l 917 1411 l 938 1370 l 960 1330 l 983 1291 l
+ 1006 1253 l 1029 1216 l 1053 1181 l 1076 1146 l 1099 1114 l
+ 1122 1083 l 1143 1053 l 1164 1026 l 1182 1001 l 1200 979 l
+ 1215 960 l 1228 943 l 1239 929 l 1248 919 l 1255 910 l
+
+ 1265 898 l gs col0 s gr gr
+
+% arrowhead
+0 slj
+n 1176 1062 m 1244 923 l 1119 1014 l 1167 1015 l 1176 1062 l 
+ cp gs 0.00 setgray ef gr  col0 s
+/Times-Roman ff 190.50 scf sf
+2250 1515 m
+gs 1 -1 sc (data is stored) col0 sh gr
+/Times-Roman ff 190.50 scf sf
+2250 1305 m
+gs 1 -1 sc (component where) col0 sh gr
+% here ends figure;
+% 
+% here starts figure with depth 10
+% Arc
+7.500 slw
+0 slc
+gs  clippath
+2422 600 m 2544 754 l 2603 708 l 2481 553 l 2481 553 l 2545 695 l 2422 600 l cp
+eoclip
+n 1986.7 1093.3 688.4 -142.5752 -32.8436 arc
+gs col0 s gr
+ gr
+
+% arrowhead
+0 slj
+n 2422 600 m 2545 695 l 2481 553 l 2470 600 l 2422 600 l 
+ cp gs 0.00 setgray ef gr  col0 s
+% here ends figure;
+% 
+% here starts figure with depth 5
+% Polyline
+0 slj
+0 slc
+7.500 slw
+n 1440 990 m 1665 990 l 1665 765 l 1440 765 l
+ cp gs /PC [[1.00 1.00 1.00] [1.00 1.00 1.00]] def
+15.00 15.00 sc P5 [16 0 0 -16 96.00 51.00] PATmp PATsp ef gr PATusp gs col7 s gr 
+% Polyline
+n 2700 1035 m 2925 1035 l 2925 810 l 2700 810 l
+ cp gs /PC [[1.00 1.00 1.00] [1.00 1.00 1.00]] def
+15.00 15.00 sc P5 [16 0 0 -16 180.00 54.00] PATmp PATsp ef gr PATusp gs col7 s gr 
+% Polyline
+n 1395 3195 m 1620 3195 l 1620 2970 l 1395 2970 l
+ cp gs /PC [[1.00 1.00 1.00] [1.00 1.00 1.00]] def
+15.00 15.00 sc P5 [16 0 0 -16 93.00 198.00] PATmp PATsp ef gr PATusp gs col7 s gr 
+% Polyline
+n 765 1215 m 990 1215 l 990 990 l 765 990 l
+ cp gs /PC [[1.00 1.00 1.00] [1.00 1.00 1.00]] def
+15.00 15.00 sc P5 [16 0 0 -16 51.00 66.00] PATmp PATsp ef gr PATusp gs col7 s gr 
+% Polyline
+n 2340 450 m 2565 450 l 2565 225 l 2340 225 l
+ cp gs /PC [[1.00 1.00 1.00] [1.00 1.00 1.00]] def
+15.00 15.00 sc P5 [16 0 0 -16 156.00 15.00] PATmp PATsp ef gr PATusp gs col7 s gr 
+/Times-Italic ff 190.50 scf sf
+1485 945 m
+gs 1 -1 sc (x') col0 sh gr
+/Times-Italic ff 190.50 scf sf
+2745 990 m
+gs 1 -1 sc (x'') col0 sh gr
+/Times-Italic ff 190.50 scf sf
+1440 3150 m
+gs 1 -1 sc (x) col0 sh gr
+/Times-Italic ff 190.50 scf sf
+810 1170 m
+gs 1 -1 sc (A) col0 sh gr
+/Times-Italic ff 190.50 scf sf
+2385 405 m
+gs 1 -1 sc (B) col0 sh gr
+% Polyline
+n 0 1980 m
+ 3960 1980 l gs col-1 s gr 
+% Polyline
+n 1980 0 m
+ 1980 3960 l gs col0 s gr 
+% here ends figure;
+% 
+% here starts figure with depth 2
+% Ellipse
+7.500 slw
+n 1350 810 45 45 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def
+15.00 15.00 sc P5 [16 0 0 -16 87.00 51.00] PATmp PATsp ef gr PATusp gs col0 s gr
+
+% Ellipse
+0.000 slw
+n 2610 810 45 45 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def
+15.00 15.00 sc P5 [16 0 0 -16 171.00 51.00] PATmp PATsp ef gr PATusp 
+% Ellipse
+n 1305 2970 45 45 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def
+15.00 15.00 sc P5 [16 0 0 -16 84.00 195.00] PATmp PATsp ef gr PATusp 
+% here ends figure;
+$F2psEnd
+rs
+end
+showpage
+%%Trailer
+%EOF
diff --git a/doc/fig/faces.fig b/doc/fig/faces.fig
new file mode 100644
index 0000000..79912c2
--- /dev/null
+++ b/doc/fig/faces.fig
@@ -0,0 +1,63 @@
+#FIG 3.2  Produced by xfig version 3.2.5-alpha5
+Portrait
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+6 0 0 3960 3960
+5 1 0 1 0 7 10 -1 -1 0.000 0 0 1 0 1986.667 1093.333 1440 675 1980 405 2565 720
+	2 1 1.00 75.00 120.00
+6 1305 765 2655 855
+1 3 0 1 0 0 2 -1 45 0.000 1 0.0000 1350 810 45 45 1350 810 1395 810
+1 3 0 0 0 0 2 -1 45 0.000 1 0.0000 2610 810 45 45 2610 810 2655 810
+-6
+6 1440 765 1665 990
+2 2 0 1 7 7 5 -1 45 0.000 0 0 -1 0 0 5
+	 1440 990 1665 990 1665 765 1440 765 1440 990
+4 0 0 4 -1 1 12 0.0000 4 150 150 1485 945 x'\001
+-6
+6 2700 810 2970 1035
+2 2 0 1 7 7 5 -1 45 0.000 0 0 -1 0 0 5
+	 2700 1035 2925 1035 2925 810 2700 810 2700 1035
+4 0 0 4 -1 1 12 0.0000 4 150 195 2745 990 x''\001
+-6
+6 1395 2970 1620 3195
+2 2 0 1 7 7 5 -1 45 0.000 0 0 -1 0 0 5
+	 1395 3195 1620 3195 1620 2970 1395 2970 1395 3195
+4 0 0 4 -1 1 12 0.0000 4 105 105 1440 3150 x\001
+-6
+6 765 990 990 1215
+2 2 0 1 7 7 5 -1 45 0.000 0 0 -1 0 0 5
+	 765 1215 990 1215 990 990 765 990 765 1215
+4 0 0 4 -1 1 12 0.0000 4 150 135 810 1170 A\001
+-6
+6 2340 225 2565 450
+2 2 0 1 7 7 5 -1 45 0.000 0 0 -1 0 0 5
+	 2340 450 2565 450 2565 225 2340 225 2340 450
+4 0 0 4 -1 1 12 0.0000 4 150 120 2385 405 B\001
+-6
+6 90 135 3870 3870
+2 2 0 0 0 7 50 -1 45 0.000 0 0 -1 0 0 5
+	 90 135 1980 135 1980 1980 90 1980 90 135
+2 2 0 0 0 7 50 -1 44 0.000 0 0 -1 0 0 5
+	 1980 1980 3870 1980 3870 3870 1980 3870 1980 1980
+2 2 0 0 0 7 50 -1 46 0.000 0 0 -1 0 0 5
+	 90 1980 1980 1980 1980 3870 90 3870 90 1980
+-6
+6 0 0 3960 3960
+2 1 0 1 -1 7 4 -1 -1 0.000 0 0 -1 0 0 2
+	 0 1980 3960 1980
+2 1 0 1 0 7 4 -1 -1 0.000 0 0 -1 0 0 2
+	 1980 0 1980 3960
+-6
+1 3 0 0 0 0 2 -1 45 0.000 1 0.0000 1305 2970 45 45 1305 2970 1350 2970
+3 2 0 1 0 -1 50 -1 -1 0.000 0 1 0 3
+	2 1 1.00 75.00 120.00
+	 1220 2923 770 1978 1265 898
+	 0.000 -1.000 0.000
+4 0 0 50 -1 0 12 0.0000 4 150 1140 2250 1515 data is stored\001
+4 0 0 50 -1 0 12 0.0000 4 195 1560 2250 1305 component where\001
+-6