Adding complex variables in C and mod in Fortran

git-svn-id: http://svn.cactuscode.org/flesh/trunk@1192 17b73243-c579-4c4c-a9d2-2d5706c11dac

2 files changed, 158 insertions, 46 deletions

diff --git a/doc/UsersGuide/FunctionReference.tex b/doc/UsersGuide/FunctionReference.tex
index f191152e..9979f297 100644
--- a/doc/UsersGuide/FunctionReference.tex
+++ b/doc/UsersGuide/FunctionReference.tex
@@ -11,13 +11,13 @@ available from C, not all are currently available from Fortran.
 
 \begin{Lentry}
 
+\item[CCTK\_Abort] 
+  [\pageref{Abort}] 
+
 \item[CCTK\_ArrayGroupSize] 
   [\pageref{ArrayGroupSize}]
   Give the size of the variables in a group, from the name
 
-\item[CCTK\_Abort] 
-  [\pageref{Abort}] 
-
 \item[CCTK\_ArrayGroupSizeB] 
   [\pageref{ArrayGroupSizeB}] 
   Give the size of the variables in a group, from either the name of the index
@@ -29,6 +29,62 @@ available from C, not all are currently available from Fortran.
 \item[CCTK\_Barrier]
   [\pageref{Barrier}] 
 
+\item[CCTK\_Cmplx]
+  [\pageref{Cmplx}]
+  Turns two real numbers into a complex number (only C)
+
+\item[CCTK\_CmplxAbs]
+  [\pageref{CmplxAbs}]
+  Returns the absolute value of a complex number (only C)
+
+\item[CCTK\_CmplxAdd]
+  [\pageref{CmplxAdd}]
+  Returns the sum of two complex numbers (only C)
+
+\item[CCTK\_CmplxConjg]
+  [\pageref{CmplxConjg}]
+  Returns the complex conjugate of a complex number (only C)
+
+\item[CCTK\_CmplxCos]
+  [\pageref{CmplxCos}]
+  Returns the Cosine of a complex number (only C) [not yet available]
+
+\item[CCTK\_CmplxDiv]
+  [\pageref{CmplxDiv}]
+  Returns the division of two complex numbers (only C)
+
+\item[CCTK\_CmplxExp]
+  [\pageref{CmplxExp}]
+  Returns the Exponentiation of a complex number (only C) [not yet available]
+
+\item[CCTK\_CmplxImag]
+  [\pageref{CmplxReal}]
+  Returns the imaginary part of a complex number (only C)
+
+\item[CCTK\_CmplxLog]
+  [\pageref{CmplxLog}]
+  Returns the Logarithm of a complex number (only C) [not yet available]
+
+\item[CCTK\_CmplxMul]
+  [\pageref{CmplxMul}]
+  Returns the multiplication of two complex numbers (only C)
+
+\item[CCTK\_CmplxReal]
+  [\pageref{CmplxReal}]
+  Returns the real part of a complex number (only C)
+
+\item[CCTK\_CmplxSin]
+  [\pageref{CmplxSin}]
+  Returns the Sine of a complex number (only C) [not yet available]
+
+\item[CCTK\_CmplxSub]
+  [\pageref{CmplxSub}]
+  Returns the subtraction of two complex numbers (only C)
+
+\item[CCTK\_CmplxSqrt]
+  [\pageref{CmplxSqrt}]
+  Returns the square root of a complex number (only C) [not yet available]
+
 \item[CCTK\_CoordIndex] 
   [\pageref{CoordIndex}] 
   Give the GF index for a given coordinate name.
@@ -65,10 +121,6 @@ available from C, not all are currently available from Fortran.
   [\pageref{Equals}] 
 
 
-\item[CCTK\_FullName] 
-  [\pageref{FullName}] 
-  Given a variable index, returns the full name of the variable
-
 \item[CCTK\_FirstVarIndex]   
   [\pageref{FirstVarIndex}] 
   Given a group name returns the first variable index in the group
@@ -77,6 +129,18 @@ available from C, not all are currently available from Fortran.
   [\pageref{FirstVarIndexI}] 
   Given a group index returns the first variable index in the group
 
+\item[CCTK\_FortranString]
+  [\pageref{FortranString}]
+  Changes a C string into a Fortran string
+
+\item[CCTK\_FullName] 
+  [\pageref{FullName}] 
+  Given a variable index, returns the full name of the variable
+
+\item[CCTK\_GroupData]   
+  [\pageref{GroupData}] 
+  Given a group index, returns information about the variables held in the group
+
 \item[CCTK\_GHExtensionHandle]   
   [\pageref{GHExtensionHandle}] 
   Get the handle associated with a extension to the Cactus GH structure
@@ -85,26 +149,22 @@ available from C, not all are currently available from Fortran.
   [\pageref{GroupIndex}] 
   Get the index number for a group name
 
-\item[CCTK\_GroupNameFromVarI]   
-  [\pageref{GroupNameFromVarI}] 
-  Given a variable index, return the name of the associated group
-
-\item[CCTK\_GroupIndexFromVarI]   
-  [\pageref{GroupIndexFromVarI}] 
-  Given a variable index, returns the index of the associated group
-
 \item[CCTK\_GroupIndexFromVar]   
   [\pageref{GroupIndexFromVar}] 
   Given a variable name, returns the index of the associated group
 
-\item[CCTK\_GroupData]   
-  [\pageref{GroupData}] 
-  Given a group index, returns information about the variables held in the group
+\item[CCTK\_GroupIndexFromVarI]   
+  [\pageref{GroupIndexFromVarI}] 
+  Given a variable index, returns the index of the associated group
 
 \item[CCTK\_GroupName]   
   [\pageref{GroupName}] 
   Given a group index, returns the group name
 
+\item[CCTK\_GroupNameFromVarI]   
+  [\pageref{GroupNameFromVarI}] 
+  Given a variable index, return the name of the associated group
+
 \item[CCTK\_GroupTypeFromVarI]   
   [\pageref{GroupTypeFromVarI}] 
   Provides group type index from the group index
@@ -129,6 +189,14 @@ available from C, not all are currently available from Fortran.
   [\pageref{NumGroups}] 
   Get the number of groups of variables compiled in the code
 
+\item[CCTK\_NumTimeLevelsFromVarI]   
+  [\pageref{NumTimeLevelsFromVarI}] 
+  Gives the number of timelevels for a variable
+
+\item[CCTK\_NumTimeLevelsFromVar]   
+  [\pageref{NumTimeLevelsFromVar}] 
+  Gives the number of timelevels for a variable
+
 \item[CCTK\_NumVars]   
   [\pageref{NumVars}] 
   Get the number of grid variables compiled in the code
@@ -141,14 +209,6 @@ available from C, not all are currently available from Fortran.
   [\pageref{NumVarsInGroup}] 
   Provides the number of variables in a group from the group name
 
-\item[CCTK\_NumTimeLevelsFromVarI]   
-  [\pageref{NumTimeLevelsFromVarI}] 
-  Gives the number of timelevels for a variable
-
-\item[CCTK\_NumTimeLevelsFromVar]   
-  [\pageref{NumTimeLevelsFromVar}] 
-  Gives the number of timelevels for a variable
-
 \item[CCTK\_nProcs]    
   [\pageref{nProcs}] 
   Get the total number of processors used
@@ -192,14 +252,14 @@ available from C, not all are currently available from Fortran.
   [\pageref{RegisterBanner}] 
   Register a banner for a thorn
 
-\item[CCTK\_RegisterCoordI] 
-  [\pageref{RegisterCoordI}] 
-  Register a grid function index as identifying a coordinate with a given coordinate name and direction.
-
 \item[CCTK\_RegisterCoord] 
   [\pageref{RegisterCoord}] 
   Register a grid function name as identifying a coordinate with a given coordinate name and direction.
 
+\item[CCTK\_RegisterCoordI] 
+  [\pageref{RegisterCoordI}] 
+  Register a grid function index as identifying a coordinate with a given coordinate name and direction.
+
 \item[CCTK\_RegisterCoordRange] 
   [\pageref{RegisterCoordRange}] 
   Saves the global upper and lower bounds for a given coordinate name
@@ -220,10 +280,6 @@ available from C, not all are currently available from Fortran.
   [\pageref{RegisterGHExtensionrfrTraverseGH}] 
   Register a routine for an extension to the Cactus GH which is run before any RFR traverse
 
-\item[CCTK\_RegisterReductionOperator] 
-  [\pageref{RegisterReductionOperator}] 
-  Register a function a providing a reduction operation
-
 \item[CCTK\_RegisterIOMethod] 
   [\pageref{RegisterIOMethod}] 
   Register an IO method name
@@ -242,6 +298,10 @@ available from C, not all are currently available from Fortran.
   [\pageref{RegisterIOMethodTriggerOutput}] 
   Register a routine for dealing with trigger output for an IO method
 
+\item[CCTK\_RegisterReductionOperator] 
+  [\pageref{RegisterReductionOperator}] 
+  Register a function as providing a reduction operation
+
 \item[CCTK\_SetupGH] 
   [\pageref{SetupGH}] 
 
@@ -249,18 +309,6 @@ available from C, not all are currently available from Fortran.
   [\pageref{SyncGroup}] 
   Synchronize the ghost zones for a group of variables
 
-\item[CCTK\_VarIndex]
-   [\pageref{VarIndex}] 
-  Get the index for a variable
-
-\item[CCTK\_VarName] 
-  [\pageref{VarName}] 
-  Given a variable index, returns the variable name
-
-\item[CCTK\_VarTypeI] 
-  [\pageref{VarTypeI}] 
-  Provides variable type index from the variable index
-
 \item[CCTK\_VarDataPtr]
   [\pageref{VarDataPtr}] 
   Returns the data pointer for a grid variable
@@ -273,6 +321,18 @@ available from C, not all are currently available from Fortran.
   [\pageref{VarDataPtrI}] 
   Returns the data pointer for a grid variable from the variable index
 
+\item[CCTK\_VarIndex]
+   [\pageref{VarIndex}] 
+  Get the index for a variable
+
+\item[CCTK\_VarName] 
+  [\pageref{VarName}] 
+  Given a variable index, returns the variable name
+
+\item[CCTK\_VarTypeI] 
+  [\pageref{VarTypeI}] 
+  Provides variable type index from the variable index
+
 \item[CCTK\_WARN] 
   [\pageref{WARN}] 
   Prints a warning message and possibly stops the code
@@ -671,6 +731,32 @@ can be either string literals (`mystring') or CCTK string parameters
 % FFF
 %%%%%
 
+\begin{CCTKFunc}{CCTK\_FortranString}{Changes a C string into a Fortran string}
+\label{FortranString}
+\subroutine{int}{integer}{nchar}
+\argument{const char *}{character*(*)}{strout}
+\argument{const char *}{CCTK\_STRING}{strin}
+\showargs
+\begin{params}
+\parameter{nchar}{The number of characters in the C string, not counting the null terminator}
+\parameter{strout}{The fortran string which on output contains the C string as the first nchar characters}
+\parameter{strin}{The (pointer to the) C string containing the null terminator}
+\end{params}
+\begin{discussion}
+String or keyword parameters in Cactus are passed into Fortran routines as 
+pointers to C strings. This means that they cannot be directly used as Fortran
+strings. This routine allows a Fortran string to be created from such a C string. Note that the Fortran string must be defined to have at least the same expected length as the C string. This routine is only callable from Fortran.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf Fortran} && \\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
 
 
 % Groups.c
diff --git a/doc/UsersGuide/ThornWriters.tex b/doc/UsersGuide/ThornWriters.tex
index eb8aa9aa..f157d74c 100644
--- a/doc/UsersGuide/ThornWriters.tex
+++ b/doc/UsersGuide/ThornWriters.tex
@@ -745,6 +745,20 @@ $(SYS_OBJD)/MyRoutine.F.o:         $(SYS_OBJD)/MyModule.F.o
 \end{verbatim}
 }
 
+\subsubsection{The {\tt MOD} function}
+
+The intrinsic function {\tt MOD} in Fortran takes two integer 
+arguments, which should both be of the same type. This means
+that it may be necessary to cast the arguements to {\it e.g}
+{\tt INT} for some architectures. This can occur in particular
+when a {\tt CCTK\_INT} parameter and the Cactus variable {\tt cctk\_iteration}
+(which is declared to be {\tt INTEGER}) are used, 
+in which case the correct code is
+{\tt
+\begin{verbatim}
+MOD(cctk_iteration,INT(MyParameter))
+\end{verbatim}
+}
 
 \subsection{C Routines}
 
@@ -816,6 +830,18 @@ void MyCRoutine(CCTK_CARGUMENTS)
 }
 \end{verbatim}
 
+\subsubsection{Complex variables}
+
+Cactus supports complex grid variables, and since there is no 
+complex data type in C, Cactus provides a number
+of functions for manipulating complex numbers to mirror the 
+functionality available in Fortran. These functions are {\tt CCTK\_Cmplx},
+{\tt CCTK\_CmplxReal}, {\tt CCTK\_CmplxImag}, {\tt CCTK\_CmplxConjg},
+{\tt CCTK\_CmplxAdd}, {\tt CCTK\_CmplxSub}, {\tt CCTK\_CmplxMul},
+{\tt CCTK\_CmplxDiv}, {\tt CCTK\_CmplxExp}, {\tt CCTK\_CmplSin},
+{\tt CCTK\_CmplxAbs}, {\tt CCTK\_CmplxLog}, {\tt CCTK\_CmplSqrt}. 
+
+
 \subsubsection{Specifically for C Programmers}
 
 Grid functions are held in memory as 1D C arrays. These are laid