======================================== KRanc Assembles Numerical Codes ======================================== What is Kranc? -------------- Kranc is a set of Mathematica scripts to convert systems of time evolution PDEs into code for numerical simulations using the Cactus infrastructure. You need Mathematica in order to use Kranc. NOTE: This README has not been updated for use with modern versions of Kranc and the instructions below will not work. What is here? ------------- README This file COPYING Licensing information - Kranc is licensed under the GPL Tools Mathematica packages used in the conversion of a PDE system to a numerical code Examples Worked out examples (massive scalar field, Maxwell equations, ADM formulation of general relativity) -- Not currently included Auxiliary Auxiliary code required for compilation of the code produced by the scripts Getting up and running with the examples ---------------------------------------- For the following instructions, we assume that you are working on a Unix-type system, and that you have Mathematica and a C compiler installed. We have tested with Mathematica version 8. The example for the Einstein equations requires a Fortran 90 compiler, as it relies on existing Fortran code for initial data. We assume that your Kranc directory lives in your home directory, so that this file is ~/Kranc/README. If this is not the case, modify the pathnames given in the following accordingly. We will be creating a standard Cactus directory as well, as ~/Cactus. These instructions are for the Klein-Gordon example, which is the simplest example. There are also notes at the end on things you need if you want to try out the other examples. Building the Massive Klein-Gordon arrangement ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Change into the directory appropriate for this example: cd ~/Kranc/Examples/KleinGordon Invoke a Mathematica command line session with input from the source file (this relies on the Kranc packages being found in the correct place relative to the current directory): math < MKGTT.m There will be some output, and an arrangement directory MKG will be created containing the thorns. A thorn list will also be created as MKG/MKG.th Installing the Cactus flesh and the required standard thorns ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Login to the cactusdevcvs repository (you only need to do this once; the login information is cached in your home directory): cvs -d :pserver:cvs_anon@cvs.cactuscode.org:/cactusdevcvs login Enter the password "anon". Check out the Cactus "flesh" from CVS. This command will check out the beta 14 version. cvs -d :pserver:cvs_anon@cvs.cactuscode.org:/cactusdevcvs co -r Cactus_4_0_Beta_14 Cactus Change into the Cactus directory: cd Cactus You can use this Cactus directory for all the examples, and all your work with Kranc. Make a directory for your thornlists: mkdir thornlists Link the MKG.th thornlist into this directory (replace with the correct path to your thornlist): ln -s ~/Kranc/Examples/KleinGordon/MKG/MKG.th thornlists/MKG.th Run the program used for checking out public thorns: gmake checkout Enter "arr" to download thorns by arrangement, choose default option to download all arrangements. Press q to quit the checkout program. For consistency with the Cactus 4.0 Beta14 release, you need to checkout the MoL thorns separately. Enter the Cactus/arrangements directory and issue the command cvs -d :pserver:cvs_anon@cvs.cactuscode.org:/cactusdevcvs co -r Cactus_4_0_Beta_14 AlphaThorns/MoL Verify that the thorns have been downloaded into the Cactus/arrangements directory. Linking the extra thorns into your Cactus installation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You should have a ~/Cactus/arrangements directory into which the standard Cactus thorns have been downloaded. Create a symbolic link from the MKG arrangement to here: ln -s ~/Kranc/Examples/KleinGordon/MKG ~/Cactus/arrangements/MKG Create a symbolic link from the KrancNumericalTools arrangement to here: ln -s ~/Kranc/Auxiliary/Cactus/KrancNumericalTools ~/Cactus/arrangements/KrancNumericalTools Building a Cactus configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You need to create a Cactus "configuration"; this is a directory in Cactus/configs in which a particular set of thorns (in this case those listed in MKG.th) are compiled. For simplicity, you may like to use a new configuration for each of the examples. However, it is also possible to manually merge the thornlists generated from many different Kranc arrangements and create just one configuration for all of them. gmake mkg-config THORNLIST=thornlists/MKG.th Now compile the configuration: gmake mkg An executable program called cactus_mkg should be created in the Cactus/exe directory. See the Cactus documentation for instructions concerning how to compile using optimization. Running the examples ~~~~~~~~~~~~~~~~~~~~ Create a directory to run Cactus in for the MKG example: mkdir MKG cd MKG Run the cactus_mkg executable with the example parameter file. ~/Cactus/exe/cactus_mkg ~/Kranc/Examples/KleinGordon/MKG100.par A directory MKG_100 will be created containing output from the run. Viewing the output ~~~~~~~~~~~~~~~~~~ Cactus based codes can generate output in many formats. For getting started we recommend ygraph (http://www.aei.mpg.de/~pollney/ygraph) to look at 1D data. ygraph MKG_100/phi_x_\[6]\[6].xg Running the other examples -------------------------- We also supply Maxwell's equations and the ADM form of the Einstein equations as examples. To run the ADM example, you will need an extra thorn ("Exact") which is not part of Cactus. cd ~/Cactus Login to the numrelcvs repository cvs -d :pserver:cvs_anon@cvs.aei.mpg.de:/numrelcvs login Password: anon Check out the necessary thorns: cvs -d :pserver:cvs_anon@cvs.aei.mpg.de:/numrelcvs co AEIThorns/Exact Link the AEIThorns arrangement into your Cactus/arrangements directory: ln -s ~/Cactus/AEIThorns ~/Cactus/arrangements/AEIThorns You also have to add the following thorns to the thornlist KrancADM.th: AEIThorns/Exact CactusEinstein/ADMCoupling CactusEinstein/CoordGauge CactusEinstein/StaticConformal NB: You will need a Fortran 90 compiler to compile the Exact thorn, and several of the standard Cactus thorns needed for Einstein's equations. We recommend the Intel Fortran Compiler, version 8 as of the time of writing. See the Cactus documentation for details about telling Cactus which compiler to use for a particular configuration. Contributing to Kranc --------------------- In order to contribute a patch to Kranc, first ensure that you are working with a clone of the Kranc repository, obtained by git clone http://github.com/ianhinder/kranc Commit your patches to your local working copy, preferably with each new feature in a separate patch, and make sure the repository is up to date by using git pull --rebase every so often. The --rebase makes sure that your commits are moved to the end of the history. It is wise to do this frequently to avoid complicated merging. When your patches are ready, use git format-patch origin which will output numbered .patch files, one per commit, to the current directory. Commits which are present in your repository but not in the public repository you cloned from (origin) will be output. Email these to the maintainers for review and inclusion. Authors: -------- Sascha Husa Christiane Lechner Ian Hinder Max Planck Institute for Gravitational Physics / Albert Einstein Institute Am Muehlenberg 1 14476 Potsdam Germany http://numrel.aei.mpg.de