diff options
| -rw-r--r-- | doc/how_to_add_a_new_model | 107 | ||||
| -rw-r--r-- | param.ccl | 112 |
2 files changed, 112 insertions, 107 deletions
diff --git a/doc/how_to_add_a_new_model b/doc/how_to_add_a_new_model new file mode 100644 index 0000000..3e319f5 --- /dev/null +++ b/doc/how_to_add_a_new_model @@ -0,0 +1,107 @@ +************************************************ +***** 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.1 2002-06-16 17:22:51 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! + 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.F: + Add a case for your new model to the decode of the character-string + model name into the integer decoded_exact_model. + src/metric.F: + 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.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.F). + 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. + src/metrics/make.code.defn: + Add the new file name to the list of files to be compiled. + +If your model needs to set up a stress-energy tensor (n.b. as described +in doc/documentation.tex, this also includes the case of a vacuum solution +with a cosmological constant), then 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.F: + 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.F + 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.) @@ -143,118 +143,16 @@ KEYWORD overwrite_boundary "Overwrite g and K on the boundary" # ################################################################################ - -# -# ***** how to add a new model ***** -# - -# -# First a general note: When adding new models or modifying existing -# ones, please follow the naming conventions described in -# doc/documentation.tex. Also, please keep the sections for various -# models in the same order in all the files. -# - -# -# To add a new model you need to modify a number of files: -# 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 shouldn't have to look -# at your source code to figure out what a given parameter means! -# this file: -# Add the new model's character-string name as another possible value -# for the exact_model parameter. -# this file: -# 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.F: -# Add a case for your new model to the decode of the character-string -# model name into the integer decoded_exact_model. -# src/metric.F: -# 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.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.F). -# 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. -# src/metrics/make.code.defn: -# Add the new file name to the list of files to be compiled. -# -# If your model needs to set up a stress-energy tensor (n.b. as described -# in doc/documentation.tex, this also includes the case of a vacuum solution -# with a cosmological constant), then 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.F: -# 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.F -# 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.) -# - -################################################################################ ##### exact_model ############################################################## ################################################################################ private: -KEYWORD exact_model "The exact solution used in thorn exact" +# +# see the file doc/how_to_add_a_new_model for instructions on adding +# a new model +# +KEYWORD exact_model "The exact solution/coordinates used in thorn exact" { # # Minkowski spacetime |