diff options
Diffstat (limited to 'doc/documentation.tex')
| -rw-r--r-- | doc/documentation.tex | 189 |
1 files changed, 189 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 |