Task: Implement WaveToy.F90 for CactusWave/WaveToyFreeF90 thorn

thorn_name: CactusWave/WaveToyFreeF90
src_filename: WaveToy.F90
interface: # Interface definition for thorn WaveToyFreeF90
# $Header$

implements: wavetoy
inherits: grid

USES INCLUDE: Symmetry.h

public:

cctk_real scalarevolve type=GF Timelevels=3
{
  phi
} "The evolved scalar field"


CCTK_INT FUNCTION Boundary_SelectVarForBC(CCTK_POINTER_TO_CONST IN GH, \
  CCTK_INT IN faces, CCTK_INT IN boundary_width, CCTK_INT IN table_handle, \
  CCTK_STRING IN var_name, CCTK_STRING IN bc_name)

REQUIRES FUNCTION Boundary_SelectVarForBC

schedule: # Schedule definitions for thorn WaveToyFreeF90
# $Header$

STORAGE: scalarevolve[3]

schedule WaveToyFreeF90_Startup at STARTUP
{
  LANG: Fortran
} "Register banner"

schedule WaveToyFreeF90_InitSymBound at BASEGRID
{
  LANG: Fortran
} "Schedule symmetries"

schedule WaveToyFreeF90_Evolution as WaveToy_Evolution at EVOL
{
  LANG: Fortran
  SYNC: scalarevolve
} "Evolution of 3D wave equation"

schedule WaveToyFreeF90_Boundaries as WaveToy_Boundaries at EVOL AFTER WaveToy_Evolution
{
  LANG: Fortran
  OPTIONS: level
} "Boundaries of 3D wave equation"

schedule GROUP ApplyBCs as WaveToyFreeF90_ApplyBCs at EVOL after WaveToy_Boundaries
{
} "Apply boundary conditions"
  
schedule WaveToyFreeF90_Boundaries as WaveToy_Boundaries at POSTRESTRICT
{
  LANG: Fortran
  OPTIONS: level
} "Boundaries of 3D wave equation"

schedule GROUP ApplyBCs as WaveToyFreeF90_ApplyBCs at POSTRESTRICT after WaveToy_Boundaries
{
} "Apply boundary conditions"

param: # Parameter definitions for thorn WaveToyFreeF90
# $Header$

restricted:
 
KEYWORD bound "Type of boundary condition to use"
{
  "none"      :: "Apply no boundary condition"
  "flat"      :: "Flat (von Neumann, n grad phi = 0) boundary condition"
  "static"    :: "Static (Dirichlet, dphi/dt=0) boundary condition"
  "radiation" :: "Radiation boundary condition"
  "robin"     :: "Robin (phi(r) = C/r) boundary condition"
  "zero"      :: "Zero (Dirichlet, phi=0) boundary condition"
} "none"


configuration: # Configuration definition for thorn CactusWave/WaveToyFreeF90
# $Header$

REQUIRES CartGrid3D

context: InitSymBound.F90:
```
 /*@@
   @file    InitSymBound.F90
   @date    
   @author  Gabrielle Allen
   @desc
            Sets the symmetries across the coordinate axes
   @enddesc
 @@*/

#include "cctk.h"
#include "cctk_Arguments.h"

 /*@@
   @routine    WaveToyFreeF90_InitSymBound
   @date      
   @author     Gabrielle Allen
   @desc 
               Sets the symmetries for Wave Toy
   @enddesc 
   @calls     
   @calledby   
   @history 
 
   @endhistory 

@@*/

subroutine WaveToyFreeF90_InitSymBound(CCTK_ARGUMENTS)
  
  implicit none
  
  DECLARE_CCTK_ARGUMENTS 

  INTEGER :: ierr  
  INTEGER, DIMENSION(3) :: sym = 1
  
  call SetCartSymVN(ierr, cctkGH, sym, 'wavetoy::phi')
  
end subroutine WaveToyFreeF90_InitSymbound

```

Startup.F90:
```
 /*@@
   @file      Startup.F90
   @date      
   @author    Gabrielle Allen
   @desc 
              Register banner 
   @enddesc 
   @version $Header$
 @@*/

#include "cctk.h"

integer function WaveToyFreeF90_Startup ()

  implicit none
   
  integer ierr
  
  call CCTK_RegisterBanner(ierr, "WaveToyFreeF90: Evolutions of a Scalar Field")

  WaveToyFreeF90_Startup = 0

end function WaveToyFreeF90_Startup

```

make.code.defn:
```
# Main make.code.defn file for thorn WaveToy
# $Header$

# Source files in this directory
SRCS = InitSymBound.F90 WaveToy.F90 Startup.F90

# Subdirectories containing source files
SUBDIRS = 

```


combined_doc_context: ## README (README):
```
Cactus Code Thorn WaveToyFreeF90
Author(s)    : Tom Goodale
               Erik Schnetter
Maintainer(s): Cactus team
Licence      : LGPL
--------------------------------------------------------------------------

1. Purpose

This thorn solves the linear wave equation, using free form (as
opposed to fixed form) Fortran 90.

```

## Documentation (.tex files):
Files: documentation.tex

```tex
=== documentation.tex ===
% *======================================================================*
%  Cactus Thorn template for ThornGuide documentation
%  Author: Ian Kelley
%  Date: Sun Jun 02, 2002
%  $Header$                                                             
%
%  Thorn documentation in the latex file doc/documentation.tex 
%  will be included in ThornGuides built with the Cactus make system.
%  The scripts employed by the make system automatically include 
%  pages about variables, parameters and scheduling parsed from the 
%  relevent thorn CCL files.
%  
%  This template contains guidelines which help to assure that your     
%  documentation will be correctly added to ThornGuides. More 
%  information is available in the Cactus UsersGuide.
%                                                    
%  Guidelines:
%   - Do not change anything before the line
%       % BEGIN CACTUS THORNGUIDE",
%     except for filling in the title, author, date etc. fields.
%   - You can define your own macros are OK, but they must appear after
%     the BEGIN CACTUS THORNGUIDE line, and do not redefine standard 
%     latex commands.
%   - To avoid name clashes with other thorns, 'labels', 'citations', 
%     'references', and 'image' names should conform to the following 
%     convention:          
%       ARRANGEMENT_THORN_LABEL
%     For example, an image wave.eps in the arrangement CactusWave and 
%     thorn WaveToyC should be renamed to CactusWave_WaveToyC_wave.eps
%   - Graphics should only be included using the graphix package. 
%     More specifically, with the "includegraphics" command. Do
%     not specify any graphic file extensions in your .tex file. This 
%     will allow us (later) to create a PDF version of the ThornGuide
%     via pdflatex. |
%   - References should be included with the latex "bibitem" command.  
%   - For the benefit of our Perl scripts, and for future extensions, 
%     please use simple latex.     
%
% *======================================================================* 
% 
% Example of including a graphic image:
%    \begin{figure}[ht]
% 	\begin{center}
%    	   \includegraphics[width=6cm]{MyArrangement_MyThorn_MyFigure}
% 	\end{center}
% 	\caption{Illustration of this and that}
% 	\label{MyArrangement_MyThorn_MyLabel}
%    \end{figure}
%
% Example of using a label:
%   \label{MyArrangement_MyThorn_MyLabel}
%
% Example of a citation:
%    \cite{MyArrangement_MyThorn_Author99}
%
% Example of including a reference
%   \bibitem{MyArrangement_MyThorn_Author99}
%   {J. Author, {\em The Title of the Book, Journal, or periodical}, 1 (1999), 
%   1--16. {\tt http://www.nowhere.com/}}
%
% *======================================================================* 

% If you are using CVS use this line to give version information
% $Header$

\documentclass{article}

% Use the Cactus ThornGuide style file
% (Automatically used from Cactus distribution, if you have a 
%  thorn without the Cactus Flesh download this from the Cactus
%  homepage at www.cactuscode.org)
\usepackage{../../../../doc/latex/cactus}

\begin{document}

% The author of the documentation
\author{} 

% The title of the document (not necessarily the name of the Thorn)
\title{}

% the date your document was last changed, if your document is in CVS, 
% please us:
%    \date{$ $Date$ $}
\date{}

\maketitle

% Do not delete next line
% START CACTUS THORNGUIDE

% Add all definitions used in this documentation here 
%   \def\mydef etc

% Add an abstract for this thorn's documentation
\begin{abstract}

\end{abstract}

% The following sections are suggestive only.
% Remove them or add your own.

\section{Introduction}

\section{Physical System}

\section{Numerical Implementation}

\section{Using This Thorn}

\subsection{Obtaining This Thorn}

\subsection{Basic Usage}

\subsection{Special Behaviour}

\subsection{Interaction With Other Thorns}

\subsection{Support and Feedback}

\section{History}

\subsection{Thorn Source Code}

\subsection{Thorn Documentation}

\subsection{Acknowledgements}


\begin{thebibliography}{9}

\end{thebibliography}

% Do not delete next line
% END CACTUS THORNGUIDE

\end{document}

```



Reference solution:
src_code:  /*@@
   @file      WaveToy.F90
   @date      
   @author    Tom Goodale
   @desc 
              Evolution routines for the wave equation solver
   @enddesc 
   @version $Header$
 @@*/

#include "cctk.h"
#include "cctk_Parameters.h"
#include "cctk_Arguments.h"
#include "cctk_Functions.h"


 /*@@
   @routine    WaveToyFreeF90_Evolution
   @date       
   @author     Tom Goodale
   @desc 
               Evolution for the wave equation
   @enddesc 
   @calls      CCTK_SyncGroup, wavetoy_boundaries
   @calledby   
   @history 
 
   @endhistory 

@@*/

subroutine WaveToyFreeF90_Evolution(CCTK_ARGUMENTS)
  
  implicit none
  
  DECLARE_CCTK_ARGUMENTS
  DECLARE_CCTK_PARAMETERS
  
  !  Declare local variables
  INTEGER   :: i,j,k
  INTEGER   :: istart, jstart, kstart, iend, jend, kend

  CCTK_REAL :: dx,dy,dz,dt
  CCTK_REAL :: dx2,dy2,dz2,dt2
  CCTK_REAL :: dx2i,dy2i,dz2i

  CCTK_REAL :: factor
  
  ! Set up shorthands
  ! -----------------
  dx = CCTK_DELTA_SPACE(1)
  dy = CCTK_DELTA_SPACE(2)
  dz = CCTK_DELTA_SPACE(3)
  dt = CCTK_DELTA_TIME

  dx2 = dx*dx
  dy2 = dy*dy
  dz2 = dz*dz
  dt2 = dt*dt

  dx2i = 1.0/dx2
  dy2i = 1.0/dy2
  dz2i = 1.0/dz2

  istart = 2
  jstart = 2
  kstart = 2
  
  iend = cctk_lsh(1)-1
  jend = cctk_lsh(2)-1
  kend = cctk_lsh(3)-1

  factor = 2*(1 - (dt2)*(dx2i + dy2i + dz2i))
  
  ! Do the evolution
  ! ----------------
  do k = kstart, kend
     do j = jstart, jend
        do i = istart, iend
           
           phi(i,j,k) = factor*phi_p(i,j,k) -           &
                phi_p_p(i,j,k) + (dt2) *                &
                ((phi_p(i+1,j,k)+phi_p(i-1,j,k))*dx2i   &
                +(phi_p(i,j+1,k)+phi_p(i,j-1,k))*dy2i   &
                +(phi_p(i,j,k+1)+phi_p(i,j,k-1))*dz2i)
           
        end do
     end do
  end do
     
end subroutine WaveToyFreeF90_Evolution


 /*@@
   @routine    WaveToyFortran_Boundaries
   @date       
   @author     Tom Goodale
   @desc 
               Boundary conditions for the wave equation
   @enddesc 
   @calls      CartSymGH,FlatBC,RadiativeBC 
   @calledby   
   @history 
 
   @endhistory 

@@*/

subroutine WaveToyFreeF90_Boundaries(CCTK_ARGUMENTS)
  
  implicit none
  
  DECLARE_CCTK_ARGUMENTS
  DECLARE_CCTK_PARAMETERS
  DECLARE_CCTK_FUNCTIONS

  CCTK_INT, parameter :: izero = 0
  integer, parameter :: ik = kind(izero)

! Local declarations
  CCTK_INT :: ierr

  CHARACTER (len=100) :: boundary
  INTEGER :: length

  ierr = 0
  
! The "bound" parameter needs to be converted into a Fortran string.
  call CCTK_FortranString(length,bound,boundary)

! Apply the outer boundary conditions
! -----------------------------------
! Note: In each of the following calls to Boundary_SelectVarForBC,
! default arguments are used, so an invalid table handle of -1 can
! be passed

  if (CCTK_EQUALS(bound,"flat") .or. CCTK_EQUALS(bound,"static")    .or. &
     CCTK_EQUALS(bound,"radiation") .or. CCTK_EQUALS(bound,"robin") .or. &
     CCTK_EQUALS(bound,"none") ) then
     ierr = Boundary_SelectVarForBC(cctkGH, int(CCTK_ALL_FACES,ik), 1_ik, -1_ik,  &
          "wavetoy::phi", boundary)
  else if (CCTK_EQUALS(bound,"zero")) then
     ierr = Boundary_SelectVarForBC(cctkGH, int(CCTK_ALL_FACES,ik), 1_ik, -1_ik,  &
          "wavetoy::phi", "Scalar")
  end if

  if (ierr < 0)  then
     call CCTK_WARN(0,"WaveToyFreeF90_Boundaries: Error selecting boundary condition")
  end if
  
end subroutine WaveToyFreeF90_Boundaries