From 597f431f8663c4adf1cb9640dea651bee659ad07 Mon Sep 17 00:00:00 2001 From: ianhin Date: Mon, 19 Jun 2006 22:25:33 +0000 Subject: Modified to document the new Kranc 2 API --- Doc/KrancDoc.tex | 868 ++++++++++++++++++++----------------------------------- 1 file changed, 312 insertions(+), 556 deletions(-) (limited to 'Doc') diff --git a/Doc/KrancDoc.tex b/Doc/KrancDoc.tex index b782583..fece360 100644 --- a/Doc/KrancDoc.tex +++ b/Doc/KrancDoc.tex @@ -2,6 +2,7 @@ \usepackage{tabularx} \usepackage{graphicx} +\usepackage{alltt} \addtolength{\oddsidemargin}{-0.25in} \addtolength{\textwidth}{1in} @@ -54,9 +55,10 @@ to produce efficient parallelized production codes. Our work is motivated by the field of numerical relativity, where Kranc is used as a research tool by the authors. The initial version of Kranc was described in \cite{KrancPaper}, and subsequent enhancements in -\cite{IHPhDThesis}. The material in this document is drawn from these -two sources, and has been updated to be consistent with the current -version of Kranc. +\cite{IHPhDThesis}. The user-visible portion of Kranc has +subsequently been redesigned. The material in this document is drawn +from these two sources, and has been updated to be consistent with the +current version of Kranc. \section{Cactus} @@ -96,60 +98,40 @@ format. These tasks are completely divorced from the physics and numerical analysis side of the problem, but are necessary in most numerical codes. + \section{Overview of the Kranc system} -There are five types of Kranc thorn: +Kranc provides a Mathematica function called {\em CreateThorn}. The +user must construct arguments and data structures for this function +describing the thorn they wish to create. A Kranc thorn can: + \begin{itemize} -\item A {\em base thorn} defines the grid functions which the -simulation will use. -\item A {\em MoL thorn} computes the right hand sides of the evolution -equations so that the time integrator can compute the evolved -variables at the next time step. This is the most important type of -thorn as it determines the system of partial differential equations -being solved. The time integration methods in Cactus require that -those grid functions containing evolved variables must be registered -as such, and the MoL thorn performs this registration. -\item A {\em setter thorn} performs a user-specified calculation at -each point of the grid. This will typically set certain grid -variables as functions of others, and can be used for various purposes -including making a change of variables or computing intermediate -quantities from evolved variables. -\item A {\em translator thorn} is a special case of a setter thorn -which converts between the evolved variables and some other set of -variables (for example, the ADMBase variables used by initial data and -analysis thorns in the context of numerical relativity) -\item An {\em evaluator thorn} computes quantities such as norms and -constraints that are used in the analysis of the constructed solution. -The calculations are invoked only when the quantities concerned are -output to permanent storage, which improves efficiency when output is -not required at each time step. +\item Define the grid functions which the simulation will use. +\item Compute the right hand sides of evolution equations so that the +time integrator can compute the evolved variables at the next time +step. The time integration methods in Cactus require that those grid +functions containing evolved variables must be registered as such, and +the MoL thorn performs this registration. +\item Performs a user-specified calculation at each point of the grid. +This will typically set certain grid variables as functions of others, +and can be used for various purposes including making a change of +variables or computing intermediate or analysis quantities from +evolved variables. \end{itemize} -These five thorn types allow complete codes to be assembled. - -Common to many of these thorn types is the idea of assigning new -values to grid functions in a loop over grid points based upon -evaluating expressions involving other grid functions. To encapsulate -this, we define a Kranc structure called a {\em -calculation}. Calculations contain lists of assignment statements for -different grid functions, and these are evaluated at each point on the -grid. Calculations can also contain temporary variables called {\em -shorthands} into which are placed intermediate expressions which are -used later in the calculation. Many of the thorn types are based -around calculation structures. +The most important data structure in Kranc is a {\em Calculation} +structure. It encapsulates the idea of assigning new values to grid +functions in a loop over grid points based upon evaluating expressions +involving other grid functions. Calculations contain lists of +assignment statements for different grid functions, and these are +evaluated at each point on the grid. Calculations can also contain +temporary variables called {\em shorthands} into which are placed +intermediate expressions which are used later in the +calculation. Calculations also contain additional information needed +by the Kranc system, such as a name for the calculation. \chapter{Using Kranc} -The user only needs to be concerned with calling functions from the -KrancThorns package. This package contains functions for creating the -different types of Kranc thorn. - -The different types of Cactus thorn used in a Kranc arrangement are -the MoL, setter, base, translator and evaluator thorns. The -KrancThorns package provides functions to create thorns of these types -given high level descriptions. These functions are the ones directly -called by users. - \section{Types of arguments} Mathematica allows two types of arguments to be passed to a function. @@ -160,30 +142,33 @@ a suitable default will be chosen. Positional arguments are useful when there are few arguments to a function, and their meaning is clear in the calling context. Named arguments are preferred when there are many arguments, as the argument names are given explicitly in the -calling context. - -For each type of Kranc thorn, there is a function to create it ({\tt -Create*Thorn}). There is a certain set of named arguments (``Common -named arguments'') which can be passed to any of these functions -(e.g.~the name of the Thorn to create, where to create it, etc). -Then, for each type of thorn, there is a specific set of named -arguments specifically for that thorn type. All of the functions -accept some positional arguments as well. -% +calling context. Named arguments are given after the positional +arguments in the form \verb|ArgumentName -> argumentvalue|. For +example: -\section{Common data structures} +\begin{center} +\begin{minipage}{0.8 \textwidth} +\begin{verbatim} +f[x, y, Sum -> True, Verbose -> True] +\end{verbatim} +\end{minipage} +\end{center} +Here the x and y are positional arguments, and Sum and Verbose are +named arguments. + +\section{Data structures} + +The user needs to pass information to Kranc in a structured way. +Mathematica does not have the concept of a C++ class or a C structure, +in which collections of named objects are grouped together for ease of +manipulation. Instead, we have defined a {\em Kranc structure} as a +list of rules of the form {\tt {\it key} -> {\it value}}. We have +chosen to use the Mathematica rule symbol ``{\tt ->}'' for syntactic +convenience. -Kranc consists of several packages which need to pass data between -themselves in a structured way. Mathematica does not have the concept -of a C++ class or a C structure, in which collections of named objects -are grouped together for ease of manipulation. Instead, we have -defined a {\em Kranc structure} as a list of rules of the form {\tt -{\it key} -> {\it value}}. We have chosen to use the Mathematica rule -symbol ``{\tt ->}'' for syntactic convenience. -% For example, one might describe a person using a ``Person'' structure as follows: -% + \begin{center} \begin{minipage}{0.8 \textwidth} \begin{verbatim} @@ -194,17 +179,131 @@ alice = {Name -> "Alice", \end{minipage} \end{center} -Once a structure has been built up, it can be parsed with the {\tt -lookup} function in the MapLookup package. {\tt lookup[structure, -key]} returns the value in {\tt structure} corresponding to {\tt key}. -For example, {\tt lookup[alice, Age]} would return the number 20. -This usage mirrors what is known as an association list (or alist) in -LISP style languages. -% Based on this concept a number of data structures have been defined -which will be used to describe the thorns to construct. Each of these +which will be used to describe the thorn to construct. Each of these data structures is introduced below. + +\subsection{Data structure: Calculation} + +Calculation structures are the core of the Kranc system. A Calculation +structure has the following form: + +\begin{center} +\begin{minipage}{0.8 \textwidth} +\begin{verbatim} +{ + Name -> name, + Schedule -> schedulestring, + Shorthands -> shorthandlist, + CollectList -> collectlist, + Equations -> equationlist +} +\end{verbatim} +\end{minipage} +\end{center} + +The {\it Shorthands} and {\it CollectList} entries are optional. + +{\it name} 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, + +\begin{center} +\begin{minipage}{0.8 \textwidth} +\begin{verbatim} +Name -> "wave_calc_rhs" +\end{verbatim} +\end{minipage} +\end{center} + +{\it schedulestring} 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. + +{\it shorthandlist} is a list of variables which are to be considered as +shorthands for the purposes of this calculation. These are 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, +\begin{center} +\begin{minipage}{0.8 \textwidth} +\begin{verbatim} +Shorthands -> {a,b} +\end{verbatim} +\end{minipage} +\end{center} +would define two shorthands called $a$ and $b$ which can be assigned +to and used in the equations. + +{\it equationlist} 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. + +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 +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. + +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. + +The following example is taken from the Kranc implementation of the +NOR formulation of Einstein's equations. It is a calculation which +describes the time evolution equation for the lapse function $\alpha$ +in {\em harmonic slicing}. It uses the TensorTools package to +represent tensorial quantities. + +\begin{center} +\begin{minipage}{0.8 \textwidth} +\begin{verbatim} +lapseEvolveCalc = +{ + Name -> "nor_harmonic_slicing", + Schedule -> {"in MoL_CalcRHS"}, + Shorthands -> {trK, hInv[ua,ub]}, + Equations -> + { + hInv[ua,ub] -> MatrixInverse[h[ua,ub]], + trK -> K[la,lb] hInv[ua,ub], + dot[alpha] -> alpha^2 trK + } +}; +\end{verbatim} +\end{minipage} +\end{center} +(The {\it MatricInverse} function is provided by TensorTools to +generate an expression for the inverse matrix.) + + + \subsection{Data structure: PartialDerivatives} The user can define partial derivative operators and associated finite @@ -347,78 +446,32 @@ generation functions. A {\tt GroupDefinition} structure lists the grid functions that are members of a specific Cactus group. A list of such structures should -be supplied to all the KrancThorns functions so that Kranc can -determine which group each grid function belongs to. - -\subsection{Data structure: Calculation} - -Calculation structures are the core of the Kranc system. The user -provides a list of equations of the form +be supplied to CreateThorn function so that Kranc can determine which +group each grid function belongs to. +The form of a GroupDefinition structure is \begin{center} \begin{minipage}{0.8 \textwidth} \begin{tt} -{\it variable} -> {\it expression} +\{{\it groupname}, \{{\it variable1, variable2, \ldots}\}\} \end{tt} \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. - -The user may specify intermediate (non-grid) variables called {\em -shorthands} which can be used as {\em variable} for precomputing -quantities which will be used later in the calculation. To identify -these variables as shorthands, they must be listed in a {\em -Shorthands} entry of the Calculation. - -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 -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. - -There is the facility for performing multiple loops in a single -calculation structure; this can be used to set a grid function in one -loop, then evaluate derivatives of it in a later loop. For this -reason, the equations are given as a list of lists of equations. - -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. - -The following example is taken from the Kranc implementation of the -NOR formulation. It is a calculation which describes the time -evolution equation for the lapse $\alpha$ in harmonic slicing. It uses -the TensorTools package to represent tensorial quantities. - +{\it groupname} is a string, and the {\it variables} are symbols. For +example, \begin{center} \begin{minipage}{0.8 \textwidth} -\begin{verbatim} -lapseEvolveCalc = { - Shorthands -> {trK, hInv[ua,ub]}, - Equations -> - {{ - hInv[ua,ub] -> MatrixInverse[h[ua,ub]], - trK -> K[la,lb] hInv[ua,ub], - dot[alpha] -> alpha^2 trK - }} -}; -\end{verbatim} +\begin{tt} +\{"sol", \{phi, pi\}\} +\end{tt} \end{minipage} \end{center} +would represent a group called {\tt sol} with variables {\tt phi} and +{\tt pi}. -\subsection{Data structure: GroupCalculation} - -A {\tt GroupCalculation} structure associates a group name with a {\tt -Calculation} which is used to update the grid functions in that -group. This is used when creating evaluator thorns, where the -calculations are triggered by requests for output for specific groups. - +The group name can be prefixed with the name of the Cactus +implementation that provides the group followed by two colons +(e.g.~``ADMBase::metric''). %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -429,17 +482,23 @@ though it is in no way tied to it. It is necessary to perform certain operations on tensorial quantities, and there was no free software available which met the requirements. -TensorTools has the following features: -\begin{itemize} -\item{It expands covariant derivatives in terms of partial derivatives -and Christoffel symbols (more than one covariant derivative can be -defined)} -\item{It expands Lie derivatives in terms of partial derivatives} -\item{Dummy indices can be automatically relabelled to avoid -conflicts} -\item{Abstract tensor expressions can be converted into component -expressions} -\end{itemize} +%% TensorTools has the following features: +%% \begin{itemize} +%% \item{It expands covariant derivatives in terms of partial derivatives +%% and Christoffel symbols (more than one covariant derivative can be +%% defined)} +%% \item{It expands Lie derivatives in terms of partial derivatives} +%% \item{Dummy indices can be automatically relabelled to avoid +%% conflicts} +%% \item{Abstract tensor expressions can be converted into component +%% expressions} +%% \end{itemize} + +%% {\bf Note: I no longer use any of the above features apart from +%% expansion into components. I prefer to do these type of calculation +%% by hand. The reason is that the way the BSSN Gammas appear from the +%% Christoffel symbols is important, and they are not visible if you use +%% these techniques.} \subsection{Representation of tensor quantities} @@ -495,446 +554,143 @@ indices in the component form. TensorTools was written mainly for automated code generation rather than symbolic manipulation; different kernels should be used for the different forms if this is a problem. -\subsection{Covariant derivatives} - -TensorTools allows the user to define more than one covariant -derivative. The following defines a covariant derivative operator -{\tt CD} with Christoffel symbol {\tt H}: -% -\mathinput{DefineConnection[CD,H]} -% -The function {\tt CDtoPD} is used to replace covariant derivatives -with partial derivatives in any expression: -% -\mathdialogue -{ - CDtoPD[CD[V[ua],lb]] -} -{ - $V^a,\,_b + H^a_{\phantom{a}bc} V^c$ -} -% -The function {\tt MakeExplicit} will automatically do this before -converting expressions into components. In order to convert an -expression containing a covariant derivative into components, -TensorTools first simplifies the expression. In the following, $x$ -and $y$ represent expressions which may contain tensorial indices. The -following steps are performed to simplify the expression: -\begin{itemize} -\item{Replace any high order covariant derivatives with repeated -application of a first order covariant derivative. This ensures that -we only need to know how to evaluate a first derivative. -$$\nabla_d \nabla_a V^b \to \nabla_d ( \nabla_a V^b)$$} -\item{Replace the covariant derivative of a product using the Leibniz -rule: $$ \nabla_a (x y) \to (\nabla_a x) y + x (\nabla_a y) $$} -\item{Replace the covariant derivative of a sum using the linearity -property: $$ \nabla_a (x + y) \to \nabla_a x + \nabla_a y $$} -\item{Replace the covariant derivative of an arbitrary expression -containing tensorial indices with its expansion in terms of a -partial derivative and Christoffel symbols, one for each -index in the expression: e.g.~$$\nabla_a V^b \to \partial_a V^b + -\Gamma^{b}_{\phantom{b}ac} V^c$$ } -\end{itemize} - - -\subsection{Lie derivatives} - -The Lie derivative of an expression $x$ with respect to a vector $V$ is -written -\mathinput{Lie[x,V]} -where $V$ has been registered using {\tt DefineTensor} and is written {\em without} -indices. The function {\tt LieToPD} is used to replace Lie derivatives -with partial derivatives: -\mathdialogue -{ - LieToPD[Lie[T[ua,lb], V]] -} -{ - $\Tud T a {b,c} V^c + \Tud T a c \Tud V c {,b} - \Tud T c b V^a_{,c}$ -} -% -Lie derivatives of products and sums are supported. -% -The function {\tt MakeExplicit} will automatically perform this replacement -before converting expressions into components. - - -\subsection{Automatic dummy index manipulation} - -When two expressions both containing a dummy index $b$ are multiplied -together, one dummy index is relabelled so as not to conflict with any -other index in the resulting expression: - -\mathdialogue -{(T[la, lb]g[ub, uc])v[ub, ld, lb]} -{$T_{ab} g^{bc} V^e_{\phantom{e}de}$} -% -This requires that every multiplication be checked for tensorial -operands. This can be a performance problem, so the feature can be -enabled and disabled with {\tt SetEnhancedTimes[True]} and {\tt -SetEnhancedTimes[False]}. It is enabled by default. - - - - - - - - - - - - - - - -\ - - - -\chapter{API reference} - -\section{Data structure specifications} -\label{app:data_structures} - -Here we describe in detail the data structures which are used when -calling the KrancThorns functions. - -\subsection{Calculation} -\label{app:Calculation} - -\begin{center} -%\begin{table} -\begin{tabularx}{\tablewidth}{|l|l|X|} - \hline - \bf Key & \bf Type & \bf Description \\ - \hline - Equations & list of lists & {\tt \{loop1, loop2\}} -- Each loop is a list - of rules of the form {\tt {\it variable} -> - {\it expression}} where - {\tt \it variable} is to be set from {\tt \it expression} \\ - Shorthands (optional) & list of symbols & Variables which are to be considered - as `shorthands' for the purposes of this calculation \\ - Name (optional) & string & A name for the calculation \\ - Before (optional) & list of strings & Function names before which the - calculation should be scheduled. \\ - After (optional) & list of strings & Function names after which the - calculation should be scheduled. \\ - \hline -\end{tabularx} -%\end{table} -\end{center} - -\subsection{GroupCalculation} -\label{app:GroupCalculation} - -A GroupCalculation structure is a list of two elements; the first is -the name (a string) of a Cactus group and the second is the -Calculation to update the variables in that group. - -\subsection{GroupDefinition} -\label{GroupDefinition} - -A GroupDefinition structure is a list of two elements. The first is -the name (string) of a Cactus group and the second is the list of -variables (symbols) belonging to that group. The group name can be -prefixed with the name of the Cactus implementation that provides the -group followed by two colons (e.g.~``ADMBase::metric''). If this is -not done, then the KrancThorns functions will attempt to guess the -implementation name, usually using the name of the thorn being -created. - -\section{KrancThorns function reference} -\label{app:function_reference} - -Here we document the arguments which can be specified for the -functions CreateBaseThorn, CreateMoLThorn, CreateSetterThorn, -CreateTranslatorThorn and CreateEvaluatorThorn. - -Note that we use Mathematica syntax for function-specific section headers. -Underscores denote function arguments, and OptArguments stands for optional -arguments, also referred to as named arguments below. These -are given in the form {\tt myFunction[..., argumentName -> argumentValue]}. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\subsection{Common Named Arguments} -\label{app:common_arguments} - -The following named arguments can be used in any of the Create...Thorn -functions: -\begin{center} -%\begin{table} -\begin{tabularx}{\tablewidth}{|X|l|X|X|} - \hline - \bf Argument & \bf Type & \bf Description & \bf Default\\ - \hline - SystemName & string & A name for the evolution system implemented by this arrangement. - This will be used for the name of the arrangement directory - & ``MyPDESystem''\\ - SystemParentDirectory & string & The directory in which to create the arrangement directory & ``.''\\ - ThornName & string & The name to give this thorn & SystemName + thorn type\\ - Implementation & string & The name of the Cactus implementation that this thorn defines & ThornName\\ - SystemDescription & string & A short description of the system implemented by this arrangement & SystemName \\ - Inherited\-Implementations & list of strings & A list of implementations to inherit from & \{\} \\ - DeBug & Boolean & Whether or not to print debugging information during thorn generation& False\\ - \hline -\end{tabularx} -%\end{table} -\end{center} -%\tableskip - -\subsection{Arguments relating to parameters} -\label{app:parameter_arguments} - -The following table describes named arguments that can be specified -for any of the thorns except CreateBaseThorn. CreateBaseThorn is -special because it can be used to define parameters which are -inherited by each thorn in the arrangement, so the arguments it can be -given are slightly different. - -%\tableskip -\begin{center} -%\begin{table} -\begin{tabularx}{\tablewidth}{|l|l|X|l|} - \hline - \bf Argument & \bf Type & \bf Description & \bf Default\\ - \hline - RealBaseParameters & list of strings & Real parameters used in this thorn but - defined in the base thorn & \{\}\\ - IntBaseParameters & list of strings & Integer parameters used in this thorn - but defined in the base thorn & \{\}\\ - RealParameters & list of strings & Real parameters defined in this thorn & \{\}\\ - IntParameters & list of strings & Integer parameters defined in this thorn & \{\}\\ - \hline -\end{tabularx} -%\end{table} -\end{center} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\subsection{CreateBaseThorn} -\label{app:CreateBaseThorn} - -Prototype: CreateBaseThorn[groups, evolvedGroupNames, primitiveGroupNames, -OptArguments - -\subsubsection{Positional arguments} - -\begin{center} -%\begin{table} -\begin{tabularx}{\tablewidth}{|l|l|X|} - \hline - \bf Argument & \bf Type & \bf Description \\ - \hline - groups & list of GroupDefinition structures & - - Definitions of any groups referred to in the other arguments. Can - supply extra definitions for other groups which will be safely - ignored. \\ - - evolvedGroupNames & list of strings & - - Names of groups containing grid functions which will be evolved by - MoL in any of the thorns in the arrangement. \\ - - primitiveGroupNames & list of strings & - - Names of groups containing grid functions which will be referred to - during calculation of the MoL right hand sides in any of the thorns - in the arrangement. \\ - - \hline -\end{tabularx} -%\end{table} -\end{center} - -\subsubsection{Named arguments} - -\begin{center} -%\begin{table} -\begin{tabularx}{\tablewidth}{|l|l|X|l|} - \hline - \bf Argument & \bf Type & \bf Description & \bf Default\\ - \hline - RealBaseParameters & list of strings & Real parameters defined in this thorn -and inherited by all the thorns in the arrangement & \{\}\\ - IntBaseParameters & list of strings & Integer parameters defined in this thorn -and inherited by all the thorns in the arrangement& \{\}\\ - \hline -\end{tabularx} -%\end{table} -\end{center} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\subsection{CreateEvaluatorThorn} -\label{app:CreateEvaluatorThorn} - -Prototype:CreateEvaluatorThorn[groupCalculations, groups, OptArguments] - -\subsubsection{Positional arguments} - -\begin{center} -%\begin{table} -\begin{tabularx}{\tablewidth}{|l|l|X|} - \hline - \bf Argument & \bf Type & \bf Description \\ - \hline - groupCalculations - & list of GroupCalculation structures - & The GroupCalculations to evaluate in order to - set the variables in each group - \\ - groups - & list of GroupDefinition structures - & Definitions for each of the groups referred to in this thorn. Can - supply extra definitions for other groups which will be safely - ignored. \\ - - \hline -\end{tabularx} -%\end{table} -\end{center} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\subsection{CreateMoLThorn} -\label{app:CreateMoLThorn} - -Prototype: CreateMoLThorn[calculation, groups, OptArguments] +%% \subsection{Covariant derivatives} + +%% TensorTools allows the user to define more than one covariant +%% derivative. The following defines a covariant derivative operator +%% {\tt CD} with Christoffel symbol {\tt H}: +%% % +%% \mathinput{DefineConnection[CD,H]} +%% % +%% The function {\tt CDtoPD} is used to replace covariant derivatives +%% with partial derivatives in any expression: +%% % +%% \mathdialogue +%% { +%% CDtoPD[CD[V[ua],lb]] +%% } +%% { +%% $V^a,\,_b + H^a_{\phantom{a}bc} V^c$ +%% } +%% % +%% The function {\tt MakeExplicit} will automatically do this before +%% converting expressions into components. In order to convert an +%% expression containing a covariant derivative into components, +%% TensorTools first simplifies the expression. In the following, $x$ +%% and $y$ represent expressions which may contain tensorial indices. The +%% following steps are performed to simplify the expression: +%% \begin{itemize} +%% \item{Replace any high order covariant derivatives with repeated +%% application of a first order covariant derivative. This ensures that +%% we only need to know how to evaluate a first derivative. +%% $$\nabla_d \nabla_a V^b \to \nabla_d ( \nabla_a V^b)$$} +%% \item{Replace the covariant derivative of a product using the Leibniz +%% rule: $$ \nabla_a (x y) \to (\nabla_a x) y + x (\nabla_a y) $$} +%% \item{Replace the covariant derivative of a sum using the linearity +%% property: $$ \nabla_a (x + y) \to \nabla_a x + \nabla_a y $$} +%% \item{Replace the covariant derivative of an arbitrary expression +%% containing tensorial indices with its expansion in terms of a +%% partial derivative and Christoffel symbols, one for each +%% index in the expression: e.g.~$$\nabla_a V^b \to \partial_a V^b + +%% \Gamma^{b}_{\phantom{b}ac} V^c$$ } +%% \end{itemize} + + +%% \subsection{Lie derivatives} + +%% The Lie derivative of an expression $x$ with respect to a vector $V$ is +%% written +%% \mathinput{Lie[x,V]} +%% where $V$ has been registered using {\tt DefineTensor} and is written {\em without} +%% indices. The function {\tt LieToPD} is used to replace Lie derivatives +%% with partial derivatives: +%% \mathdialogue +%% { +%% LieToPD[Lie[T[ua,lb], V]] +%% } +%% { +%% $\Tud T a {b,c} V^c + \Tud T a c \Tud V c {,b} - \Tud T c b V^a_{,c}$ +%% } +%% % +%% Lie derivatives of products and sums are supported. +%% % +%% The function {\tt MakeExplicit} will automatically perform this replacement +%% before converting expressions into components. + + +%% \subsection{Automatic dummy index manipulation} + +%% When two expressions both containing a dummy index $b$ are multiplied +%% together, one dummy index is relabelled so as not to conflict with any +%% other index in the resulting expression: + +%% \mathdialogue +%% {(T[la, lb]g[ub, uc])v[ub, ld, lb]} +%% {$T_{ab} g^{bc} V^e_{\phantom{e}de}$} +%% % +%% This requires that every multiplication be checked for tensorial +%% operands. This can be a performance problem, so the feature can be +%% enabled and disabled with {\tt SetEnhancedTimes[True]} and {\tt +%% SetEnhancedTimes[False]}. It is enabled by default. + + +\section{Creating a Kranc thorn} + +Prototype: CreateThorn[groups, directory, thornName, namedArgs]\\ + +Note that if you want to use TensorTools tensors in calculations, you +must call the CreateThornTT function instead of this one. It takes the +same arguments, but they can be tensorial in nature. \subsubsection{Positional Arguments} \begin{center} -%\begin{table} \begin{tabularx}{\tablewidth}{|l|l|X|} \hline \bf Argument & \bf Type & \bf Description \\ \hline - calculation & Calculation & The calculation for setting the right hand side variables - for MoL. The equations should be of the form - {\tt dot[{\it gf}] -> {\it expression}} for evolution equations, and - {\tt {\it shorthand} -> {\it expression}} for shorthand definitions, which can - be freely mixed in to the list.\\ - groups & list of GroupDefinition structures - -& Definitions for each of the groups referred to in this thorn. Can - supply extra definitions for other groups which will be safely - ignored. \\ + groups & list of GroupDefinition structures & These define what groups each grid function is a member of. \\ + directory & string & What directory to create the thorn in. Usually ".". \\ + thornName & string & The name to give the thorn. \\ + namedArgs & Rule & The named arguments (see below) \\ \hline \end{tabularx} -%\end{table} \end{center} \subsubsection{Named Arguments} \begin{center} -%\begin{table} -\begin{tabularx}{\tablewidth}{|l|l|X|l|} +\begin{tabularx}{\tablewidth}{|l|X|X|l|} \hline \bf Argument & \bf Type & \bf Description & \bf Default\\ \hline - PrimitiveGroups & list of strings & These are the groups containing the grid functions which are - referred to but not evolved by this evolution thorn & \{\} \\ - \hline -\end{tabularx} -%\end{table} -\end{center} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + Calculations & list of Calculation structures & The calculations to perform & \{\} \\ -\subsection{CreateSetterThorn} -\label{app:CreateSetterThorn} + DeclaredGroups & list of strings & The names of groups present in the {\tt groups} argument + which are to be created as new groups by this thorn. & \{\} \\ -Prototype: CreateSetterThorn[calculation, OptArguments] + PartialDerivatives & a PartialDerivatives structure & The partial derivative definitions that + are used in this thorn (optional). & \{\} \\ -\subsubsection{Positional Arguments} - -\begin{center} -%\begin{table} -\begin{tabularx}{\tablewidth}{|l|l|X|} - \hline - \bf Argument & \bf Type & \bf Description \\ - \hline - calculation & Calculation & The calculation to be performed \\ + RealParameters & list of strings & A list of real-valued parameters that this thorn will + define and use. They will all default to zero. (optional) & \{\} \\ - groups & list of GroupDefinition structures + IntParameters & list of strings & A list of integer-valued parameters that this thorn will + define and use. They will all default to zero. (optional) & \{\} \\ -& Definitions for each of the groups referred to in this thorn. Can - supply extra definitions for other groups which will be safely - ignored. \\ + KeywordParameters & list of KeywordParameterDefinition structures & A list of parameter definition structures for all the keyword parameters which this thorn will define and use. (optional) & \{\} \\ + InheritedImplementations & list of strings & A list of all the implementations which this thorn + will inherit from. This is necessary to use grid functions + provided by these implementations. (optional) & \{\} \\ \hline \end{tabularx} -%\end{table} \end{center} -\subsubsection{Named Arguments} - -\begin{center} -%\begin{table} -\begin{tabularx}{\tablewidth}{|l|l|X|l|} - \hline - \bf Argument & \bf Type & \bf Description & \bf Default\\ - \hline - SetTime (optional) & string & ``initial\_and\_poststep'', - ``initial\_only'' - or ``poststep\_only'' & ``initial\_and\_poststep'' \\ - \hline -\end{tabularx} -%\end{table} -\end{center} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{CreateTranslatorThorn} -\label{app:CreateTranslatorThorn} - -Prototype:CreateTranslatorThorn[groups, OptArguments] - -\subsubsection{Positional Arguments} - -\begin{center} -%\begin{table} -\begin{tabularx}{\tablewidth}{|l|l|X|} - \hline - \bf Argument & \bf Type & \bf Description \\ - \hline - - groups & list of GroupDefinition structures - -& Definitions for each of the groups referred to in this thorn. Can - supply extra definitions for other groups which will be safely - ignored. \\ - \hline -\end{tabularx} -%\end{table} -\end{center} - -\subsubsection{Named Arguments} - -\begin{center} -%\begin{table} -\begin{tabularx}{\tablewidth}{|l|l|X|} - \hline - \bf Argument & \bf Type & \bf Description\\ - \hline - TranslatorInCalculation & Calculation & The calculation to set the evolved - variables from some other source \\ - TranslatorOutCalculation & Calculation & The calculation to convert the evolved - variables back into some other set of - variables \\ - \hline -\end{tabularx} -%\end{table} -\end{center} - -- cgit v1.2.3