From c596fcf0dd3c1c43540b54089feb78b245bd4cd1 Mon Sep 17 00:00:00 2001 From: Ian Hinder Date: Sat, 7 Aug 2010 17:37:01 +0200 Subject: KrancDoc.tex: More updates to documentation --- Doc/KrancDoc.tex | 213 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 158 insertions(+), 55 deletions(-) (limited to 'Doc') diff --git a/Doc/KrancDoc.tex b/Doc/KrancDoc.tex index 11af087..d495c06 100644 --- a/Doc/KrancDoc.tex +++ b/Doc/KrancDoc.tex @@ -85,17 +85,16 @@ For example, Kranc makes uses of existing Cactus thorns which provide: computational grid. \item Scheduling of parts of the code based upon parameters. \item Standard efficient time integrators such as fourth order -Runge-Kutta and iterative Crank-Nicolson via the {\em MoL} thorn -written by I.~Hawke. + Runge-Kutta via the {\em MoL} thorn written by I.~Hawke. \item Mesh refinement \cite{Schnetter}; i.e., using variable resolution across the numerical grid, so that the computational resources are focused on interesting parts of the simulation. -\item Automatic parallelization of the code to run across multiple +\item Automatic parallelization of the code via MPI to run across multiple processors on a supercomputer or cluster, both to improve computational speed and to use larger grids than can be stored in the memory of a single node. \item Output of grid variables to permanent storage in a structured -format. +format, for example HDF5. \end{itemize} These tasks are completely separate from the physics and numerical analysis side of the problem, but are necessary in most numerical @@ -202,14 +201,17 @@ structure has the following form: \bf Key & \bf Type & \bf Description & \bf Default\\ \hline Name & String & The name of the calculation & (none) \\ - Equations & List of rules & The assignments that this calculation will perform & \{\} \\ Schedule & List of Strings & Cactus schedule specifications & Automatic \\ Shorthands & List of Symbols & Temporary variables which will be used in this calculation & \{\} \\ - CollectList & List of Symbols & Variables which will be used by Collect in Simplify & \{\} \\ Where & Everywhere / Interior / Boundary & Which part of the grid this calculation will be performed on & Everywhere \\ + ConditionalOnKeyword & \{String, String\} & + The calculation will only be performed if the parameter named by the first string has the value specified by the second string. & \\ + ConditionalOnKeywords & \{\{String, String\}, \ldots \} & + The same as ConditionalOnKeyword, but all the parameters must have their corresponding values for the calculation to be performed.& \\ + ConditionalOnTextuals & List of Strings & Conditional expressions to be inserted in the Cactus schedule.ccl for the calculation to be performed. & \{\} \\ + CollectList & List of Symbols & Variables which will be used by Collect in Simplify & \{\} \\ NoSimplify & True/False & Whether to disable simplification of the equations for this calculation & False \\ - ConditionalOnTextuals & List of Strings & Conditional expressions to be inserted in the Cactus schedule.ccl & \{\} \\ DeclarationIncludes & List of Strings & Cactus include files to use in this thorn & \{\} \\ \hline \end{tabularx} @@ -222,8 +224,9 @@ values if omitted. The name of a calculation is a string which will be used as the function name in Cactus, as well as the base of the filename of the -source file implementing the calculation in the generated thorn. For -example, +source file implementing the calculation in the generated thorn. + +Example: \begin{center} \begin{minipage}{0.8 \textwidth} @@ -233,76 +236,176 @@ Name -> "wave_calc_rhs" \end{minipage} \end{center} +\subsubsection{Equations} + +The equation list is a list of assignments to perform in the +calculation loop. Each equation is of the form +\begin{center} +\begin{minipage}{0.8 \textwidth} +\begin{verbatim} +variable -> expression +\end{verbatim} +\end{minipage} +\end{center} +When the calculation is performed, for each point in the grid, {\it +expression} is evaluated and placed into the grid function {\it +variable}. Here {\it expression} may contain partial derivatives of +grid functions which have been defined in a PartialDerivatives +structure. {\it variable} may be either a grid function or a +shorthand. Using the notation {\tt dot[{\it gf}]} for {\it variable} +represents a time derivative of the grid function {\it gf}; this +should be used when the calculation is scheduled in {\tt MoL\_CalcRHS} +for calculating the right hand sides of the evolution equations. + +It is possible to use the same variable (either a grid function or a +shorthand) on both the left hand side and the right hand side of an +equation assignment. However, in that case the variable must not be +differentiated on the right hand side, as this would lead to a result +which depended on the ordering of the loop over the grid points, which +is almost certainly not what is intended. Kranc will detect such a +differentiation and abort with an error. See the option +ProhibitAssignmentToGridFunctionsRead to CreateThorn in +Sec.\ref{sec:createthornopts} if you want to prohibit such assignments +altogether. + \subsubsection{Schedule} -This is a Cactus schedule specification describing -when in the simulation the calculation will be performed. At its -simplest, it can be given as one of the following: -\begin{itemize} -\item {\tt "at INITIAL"} -\item {\tt "in MoL\_CalcRHS"} -\item {\tt "at ANALYSIS"} -\end{itemize} -so that the calculation is performed in either the initial data time -bin, the schedule group for calculating right hand sides of evolution -equations, or the analysis time bin. This is given as a list to allow -the calculation to be scheduled at multiple points. Omitting the -schedule information causes Kranc to schedule the calculation -automatically. Currently, this is used for analysis quantities which -are scheduled in \verb|MoL_PseudoEvolution| and have boundary -conditions applied after them. +This is a list of Cactus schedule specifications describing when in +the simulation the calculation will be performed. Multiple schedule +strings can be provided to allow the calculation to be scheduled at +multiple points. Omitting the schedule information causes Kranc to +schedule the calculation automatically. Currently, this is used for +analysis quantities which are scheduled in \verb|MoL_PseudoEvolution| +and have boundary conditions applied after them. + +Examples: + +\begin{center} +\begin{minipage}{0.8 \textwidth} +\begin{verbatim} +Schedule -> {"at INITIAL"} +Schedule -> {"in MoL_CalcRHS"} +Schedule -> {"at ANALYSIS"} +\end{verbatim} +\end{minipage} +\end{center} \subsubsection{Shorthands} -This is a list of variables which are to be considered as -shorthands for the purposes of this calculation. These are variables +This is a list of variables which are to be considered as shorthands +for the purposes of this calculation. These are temporary variables which are defined locally in the loop and are not grid functions -defined over the whole grid. They are used as temporary intermediate -variables when setting more complicated grid functions. For example, +defined over the whole grid. They are used as intermediate variables +when setting more complicated grid functions. Since they are defined +only pointwise, they cannot be differentiated. + +Examples: + \begin{center} \begin{minipage}{0.8 \textwidth} \begin{verbatim} Shorthands -> {a,b} +Shorthands -> {hInv[ua,ub], alpha, Ric[la,lb]} \end{verbatim} \end{minipage} \end{center} -would define two shorthands called $a$ and $b$ which can be assigned -to and used in the equations. -\subsubsection{Equations} +\subsubsection{Where} + +Different calculations need to be evaluated on different portions of +the numerical grid. For example, a calculation which implements a +boundary condition needs to be performed on the boundary points only. +A calculation which contains derivatives needs to be performed on the +interior of the grid only. A calculation which does not contain +derivatives can be performed even in the ghost zones, so that a +potentially time-consuming synchronisation can be avoided. The Where +option can have values of Everywhere, Interior or Boundary +corresponding to these choices. There is currently no check that a +calculation containing derivatives is not performed on the entire +grid, nor that the number of ghost zones selected by the user at run +time is compatible with the finite differencing operator chosen. + +Examples: +\begin{center} +\begin{minipage}{0.8 \textwidth} +\begin{verbatim} +Where -> Everywhere +\end{verbatim} +\end{minipage} +\end{center} -The equation list is a list of assignments to perform in the -calculation loop. Each equation is of the form +\subsubsection{ConditionalOnKeyword} + +This key allows a calculation to be performed conditionally based on +the value of a parameter set by the user at run time. Setting \begin{center} \begin{minipage}{0.8 \textwidth} \begin{verbatim} -variable -> expression +ConditionalOnKeyword -> {, } \end{verbatim} \end{minipage} \end{center} -When the calculation is performed, for each point in the grid, {\it -expression} is evaluated and placed into the grid function {\it -variable}. Here {\it expression} may contain partial derivatives of -grid functions which have been defined in a PartialDerivatives -structure. {\it variable} may be either a grid function or a -shorthand. Using the notation {\tt dot[{\it gf}]} for {\it variable} -represents a time derivative of the grid function {\it gf}; this -should be used when the calculation is scheduled in {\tt MoL\_CalcRHS} -for calculating the right hand sides of the evolution equations. +where \verb|| is a string naming a keyword parameter defined in +the KeywordParameters option to CreateThorn will cause the calculation +to be performed only if that parameter is set to \verb||. + +Example: -The arrangement of the terms in the equations can have a marked effect -on both compile time and run time. It is often helpful to tell +\begin{center} +\begin{minipage}{0.8 \textwidth} +\begin{verbatim} +ConditionalOnKeyword -> {"gauge_condition", "harmonic"} +\end{verbatim} +\end{minipage} +\end{center} + +\subsubsection{ConditionalOnKeywords} + +The ConditionalOnKeywords key takes a list of +\verb|{, }| pairs as described under +ConditionalOnKeyword. All the parameters must match for the +calculation to be scheduled. + +\subsubsection{ConditionalOnTextuals} + +This key can be set to a string which is used verbatim in the Cactus +schedule.ccl file. Any valid Cactus conditional string can be used. + +\subsubsection{CollectList} + +The arrangement of the terms in the equations can have a significant +effect on both compile time and run time. It is often helpful to tell Mathematica to collect the coefficients of certain types of term, -rather than expanding out entire expressions. To this end, the user -can include a {\em CollectList} entry in a calculation; this is a list -of variables whose coefficients should be collected during -simplification. +rather than expanding out entire expressions. The user can include a +{\em CollectList} entry in a calculation; this is a list of variables +whose coefficients should be collected during simplification. + +\subsubsection{NoSimplify} + +Setting this option to True stops Kranc from simplifying the right +hand sides of expressions in this calculation. This could be used +because the user has found a way of writing the expressions which +leads to faster code than if Kranc's simplification is used, or +because the expressions are so complicated that the simplification +takes a very long time to perform. + +Example: + +\begin{center} +\begin{minipage}{0.8 \textwidth} +\begin{verbatim} +NoSimplify -> True +\end{verbatim} +\end{minipage} +\end{center} + +\subsubsection{DeclarationIncludes} -Note that the system is not designed to allow the same grid function -to be set more than once in a single loop of a calculation. This -limitation may be removed in the future. +This is a list of filenames which will be \verb|#include|ed in the +generated code inside the calculation function but before the loop +over grid points. -\subsubsection{Example} +\subsubsection{{\it Calculation Example}} The following example is taken from the Kranc implementation of the NOR formulation of Einstein's equations. It is a calculation which @@ -469,7 +572,7 @@ dot[v] -> PDstandard2nd[v,1] + Diss2nd[v] \end{center} A PartialDerivatives structure is given as an argument to the thorn -generation functions. +generation function CreateThorn. \subsection{Data structure: GroupDefinition} -- cgit v1.2.3