1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
************************************************
***** How to Add a New Model to this Thorn *****
************************************************
$Header: /usr/local/svn/cvs-repositories/numrelcvs/AEIThorns/Exact/doc/how_to_add_a_new_model,v 1.5 2003-05-23 16:35:44 jthorn Exp $
A general note: Please keep the sections for various models in the
same order in all the files. This makes it _much_ easier for people
to navigate around in the files...
To add a new model you need to modify a number of files:
First, choose a character-string name for your new model, following the
naming conventions described in doc/documentation.tex .
Then you need to modify...
doc/documentation.tex:
Add a section describing your new model. Please try to give
references for the "big picture" of the physics, preferably to
gr-qc and/or well-known books. Please also explain the physics
meanings of all the parameters -- users should *not* have to look
at your source code to figure out what a given parameter means!
README
Add a line or two giving the copyright status of your new code.
You can either put this in one of the existing licensing sections,
or create a new licensing section and add your copyright information
there.
param.ccl:
Add the new model's character-string name as another possible value
for the exact_model parameter.
param.ccl:
Add a section later in this file giving the new model's parameters.
(If there are no parameters this section should still be present,
with a comment that there are no parameters.)
src/include/param_defs.inc:
Add a #define for your new model.
(You can renumber the existing values if you need to... but if
you do, make sure you do a make your-configuration-name-realclean
and recompile not just this thorn, but also all the evolution
thorns.)
src/decode_pars.F77:
Add a case for your new model to the decode of the character-string
model name into the integer decoded_exact_model.
src/metric.F77:
Add a case for your new model to the decode of decoded_exact_model,
calling a (new) subroutine named for your new model.
src/metrics/your_model_name.F77 (or .F90 or .F)
Create a new file in this directory with a Fortran 77/90 subroutine
to compute the metric and the inverse metric for your new model
(this is the subroutine you just added a call to, in src/metric.F77).
It's probably easiest to start with a copy of an existing file and
modify it to compute your new metric -- that will help you get all
the "boilerplate" code right.
Please put a comment at the top of the file giving your name,
a copyright line, and the licensing status of the file (GPL, LGPL,
GPL-with-the-usual-Cactus-exemption-for-linking-with-non-GPL-thorns,
top-secret-you-can-look-at-it-but-then-we-have-to-shoot-you, whatever).
One additional information about the conformal factor which is passed
to the function: It is preset to 1.0 or 0.0 according to the fact if
it is wanted or not. If you want to have a physical metric, just do not
change it.
src/metrics/make.code.defn:
Add the new file name to the list of files to be compiled.
You need to modify some additional files:
interface.ccl:
Add copies of all your model's CCTK_INT and/or CCTK_REAL parameters
to the Exact_pars_int and/or Exact_pars_real variable groups as
appropriate, changing the "__" in the parameter names to "___".
If you have CCTK_COMPLEX parameters, add a corresponding variable
group and do the same thing. If you have KEYWORD or STRING
parameters, see below.
src/decode_pars.F77:
Add a block of code for your new model to copy all the model's
parameters to the corresponding "___" grid scalars.
src/include/Scalar_CalcTmunu.inc:
Add a case for your new model to *add* the stress-energy tensor
contribution on to the variables Ttt ... Tzz. Note that this code
will be compiled as part of various evolution thorns -- it doesn't
have access to this thorn's parameters, only to the "___" grid
scalars (that's why the "___" stuff is there in the first place!).
src/include/Scalar_CalcTmunu_temps.inc:
If you need temporary variables in your Scalar_CalcTmunu.inc
code, declare them here.
If your model has a KEYWORD or STRING parameter(s) and needs to set up
a stress-energy tensor, then because Cactus doesn't allow grid scalars
of these data types, you need to decode these parameter(s) into integers:
interface.ccl
Add CCTK_INT parameters for the decoded integer values.
src/include/param_defs.inc:
Add a new set of #defines giving all the possible values
of the decoded integer(s) for your keyword/string parameter(s).
src/decode_pars.F77
Add a block of code for your new model to decode the KEYWORD
and/or STRING parameters into integers. Don't forget to
include a CCTK_WARN(0, "...") if the code doesn't recognize
the string -- this helps to catch bugs where you (or someone
else) misspells one of the strings somewhere.
Finally, please add a test suite for your new model to the test/
directory. (Alas, many of the existing models lack tests. Sigh...)
The Cactus Users' Guide has a section "Adding a test suite" (as of
this writing it's section B9.5) which explains how this works; basically
you just need to create
test/my-test-name.par
test/my-test-name/output-file-1
test/my-test-name/output-file-2
test/my-test-name/output-file-3
etc. (The test should create the subdirectory itself, and write ASCII
output files there. You can do this by including IOUtil in your thorn
list and putting
IO::out_dir = "my-test-name"
IO::parfile_write = "false"
in your test parameter file.)
|
