IllinoisGRMHD

Guide to Getting Started

Step 0: Read the Requirements section of this document to make sure you have installed all software packages on which IllinoisGRMHD and Einstein Toolkit's Cactus/Carpet adaptive-mesh refinement (AMR) infrastructure depend. In addition, to run the test simulation, you will need a computer with at least 6--8GB of RAM. To visualize the output, please install gnuplot.
Step 1: Click here to download the September 2015 version of IllinoisGRMHD and Einstein Toolkit software package.
Step 2: Unpackage the software via
tar zxfv IllinoisGRMHD_Sept_1_2015_public_release__based_on_ET_2015_05.tar.gz
Step 3: Enter the directory containing the uncompressed package:
cd IllinoisGRMHD_Sept_1_2015_public_release__based_on_ET_2015_05
Step 4: Edit the
make_config-runmefirst
script to specify your computer's configuration. Then run the script via
./make_config-runmefirst
Step 5: If the above step is unsuccessful, install needed software packages based on the error messages and repeat Step 4. Otherwise, continue to Step 6.
Step 6: Type
make etilgrmhd
and wait for the code to compile. The full compile will take around 30 minutes or so on a fast (ca. 2015) desktop. So relax and grab a hot drink, but be quick! Compilations are fun to watch... [next step]
Step 7: ... until they fail. If the compilation fails, be careful not to spill your hot drink, check Step 0 again, then return to Step 4 and verify that your computer's configuration is consistent. If you see the same error message when you return to this step, email users*at*einsteintoolkit.org with your error message and your computer's set up. Be sure to mention that you are trying to compile IllinoisGRMHD.
Step 8: Once the compilation succeeds, pat yourself on the back and go to the subdirectory containing the executable:
cd exe
where you will find the executable and a simulation parameter file called
tov_star_parfile_for_IllinoisGRMHD.par
This parameter file tells the executable what software packages to load and what parameters to feed those packages. In this case, it initializes IllinoisGRMHD and a number of other packages to perform a simulation of a TOV star, which is a model of a stable neutron star. To start the simulation, type the command:
./cactus-etilgrmhd tov_star_parfile_for_IllinoisGRMHD.par
This is not a large-scale simulation by any stretch, but you will need to run on a computer with at least 6--8GB of RAM. Allow the simulation to proceed to Iteration 256 at least... it may take a while, depending on the speed of your computer. But just think, your computer is running a simulation of a neutron star, solving Einstein's equations of general relativity, coupled to the equations of general relativistic hydrodynamics (this is an unmagnetized star). It is now time call your mom and tell her how cool you are.
Step 9: As the simulation runs, data will be output to the subdirectory called
exe/tov_star_parfile_for_IllinoisGRMHD/
There is one ASCII file in this subdirectory called
illinoisgrmhd::grmhd_primitives_allbutbi.maximum.asc
This file stores the maximum values of rest-mass density (column 3), pressure (column 4), 3-velocities (x,y,z components: columns 5-7), and u^0 (column 8), versus iteration (column 1) and physical time (column 2).
Step 10: Plot the maximum rest-mas density of the star versus time, by first starting gnuplot:
gnuplot
Next, plot column 2 versus column 3:
p "illinoisgrmhd::grmhd_primitives_allbutbi.maximum.asc" u 2:3 w lp
the "w lp" at the end of the command indicates that you would like to plot with lines that connect the data points, with both lines and points plotted together. You should see a plot that looks something like this: This plot shows us that the maximum density of the star (located at the star's center) undergoes some fluctuations, despite the fact that this star is supposed to be initially in equilibrium. What gives? The answer lies in the fact that our simulation evaluates derivatives in the aforementioned equations only approximately. In fact, for a grid spacing Delta x, the derivatives are only accurate to (Delta x)^2. This is demonstrated in the upper-right panel of Figure 3 in the IllinoisGRMHD code announcement paper, which serves as a great starting point for jumping in and understanding the basics of the IllinoisGRMHD code.
Step 11: We conclude this Guide for Getting Started by pointing the reader to the basic source code directories within the package. Please note that all software is released under the GNU General Public License, version 2.0 or higher. The IllinoisGRMHD source code is located in the
arrangements/WVUThorns/IllinoisGRMHD/
subdirectory. In
arrangements/WVUThorns/IllinoisGRMHD/src/
you will find the C source code, and
arrangements/WVUThorns/IllinoisGRMHD/doc/
contains basic documentation, beyond what is found in the paper. In the
arrangements/WVUThorns/ID_converter_ILGRMHD/
subdirectory you will find the software that enables IllinoisGRMHD to be used with any Einstein Toolkit initial data module.

Open Source Friends

Guide to Getting Started

Step 1: Click here to download the September 2015 version of IllinoisGRMHD and Einstein Toolkit software package.

Step 2: Unpackage the software via

Step 3: Enter the directory containing the uncompressed package:

Step 4: Edit the

script to specify your computer's configuration. Then run the script via

Step 5: If the above step is unsuccessful, install needed software packages based on the error messages and repeat Step 4. Otherwise, continue to Step 6.

Step 6: Type

and wait for the code to compile. The full compile will take around 30 minutes or so on a fast (ca. 2015) desktop. So relax and grab a hot drink, but be quick! Compilations are fun to watch... [next step]

Step 8: Once the compilation succeeds, pat yourself on the back and go to the subdirectory containing the executable:

where you will find the executable and a simulation parameter file called

Step 9: As the simulation runs, data will be output to the subdirectory called

There is one ASCII file in this subdirectory called

This file stores the maximum values of rest-mass density (column 3), pressure (column 4), 3-velocities (x,y,z components: columns 5-7), and u^0 (column 8), versus iteration (column 1) and physical time (column 2).

Step 10: Plot the maximum rest-mas density of the star versus time, by first starting gnuplot:

Next, plot column 2 versus column 3:

Step 11: We conclude this Guide for Getting Started by pointing the reader to the basic source code directories within the package. Please note that all software is released under the GNU General Public License, version 2.0 or higher. The IllinoisGRMHD source code is located in the

subdirectory. In

you will find the C source code, and

contains basic documentation, beyond what is found in the paper. In the

subdirectory you will find the software that enables IllinoisGRMHD to be used with any Einstein Toolkit initial data module.