Setup¶
Installation¶
Install Griddr by first obtaining the code from the public repository at Bitbucket using git by opening a terminal in the location you want the griddr directory created and executing
git clone https://rickdnewton@bitbucket.org/rickdnewton/griddr.git
then you obtain HDF5 (necessary for reading some simulation files) and set its location in the Makefile (as well as defining your compiler), then simply
make
to produce two binary files, one for use with periodic simulations, ‘Griddr-P’, and one for non-periodic, ‘Griddr-NP’.
Mac installation guide¶
If you are installing griddr on a Mac computer then additional dependencies must be obtained. We recommend the use of MacPorts for easily obtaining the necessary C/C++ libraries, and Anaconda for the Python dependencies, although other alternatives exist. The installation and use of Griddr requires the use of a Terminal instance.
Note
You should have Xcode installed to make system libraries and compilers available when using programs provided as source code and for installing many codes through MacPorts.
- Install MacPorts
- using the installer which can be obtained from here
- Install HDF5 libraries
- via the terminal using MacPorts by entering sudo port install hdf5
- Compile Griddr
- Open a terminal in the Griddr src/ directory and enter make to produce the code binaries in bin/
If you wish to use the Python wrapper for Griddr or the bundled utilities for image generation then you may need to install Python; in this case
- Install Anaconda
- using the installer which can be obtained from here
- ensure you have the most up-to-date version by running conda update conda
- Install iPython to give you the ability to interactively work with the data and Matplotlib to allow the plotting and image generation
- conda install ipython
- conda install matplotlib
Choice of Compiler¶
When using any C/C++ software distributed as source code, it is necessary to make use of a compiler. The compiler takes the text codes written by the programmer and turns them in to a single executable file, or binary, which is then run to begin the program. Installing Griddr using GNU C++ compiler (g++) should be relatively painless on Linux, however Modern Mac OS does not ship with the g++ installed as standard, instead using it as an alias for the LLVM clang compiler.
Either compiler can be used in principle, however at the time of writing clang does not support multithreading through OpenMP which has some limited use in Griddr.
In order to use clang, it is necessary to change two lines in the Makefile, the relevant lines chould be changed to
CC = clang -std=c++11 -stdlib=libc++
...
LIBS = $(HDF5_LIBS) -lm -lc++
If instead you wish to install and use g++ you may simply install it via MacPorts with, for example
sudo port install gcc49
after which you can either use gcc-mp-4.9 as your compiler in the Makefile, or set the gcc alias to point to the GNU compiler instead of clang with
sudo port select --set gcc mp-gcc49
where you can see which compilers are available by entering port select --list gcc.
Updating the Code¶
Updated versions of the code will be pushed periodically to the Bitbucket repository. To take advantage of these updates and bug-fixes, you open a terminal in the griddr/ parent directory, then pull the updated code onto your machine with
git pull
before moving into the source code directory cd src/ and re-building the code
make clean
make
Additional Makefile options¶
The code contains various preprocessor commands to change its default behaviour. By activating (i.e. uncommenting, removing the # symbol) any of the following options in the Makefile and re-compiling the code (e.g. with make clean; make), we can get different products from the code.
To compile the code in a version which produces three dimensional grids rather than two:
OPT += -DTHREE_DIMS
The code may be instructed to emply a simplifying assumption in the gridding algorithm whereby all particles are assumed to lie at the centres of their cells, meaning that tabulated radius tables can be used. To activate this mode use:
OPT += -DFAST_PLOT
The following options are only valid if used with 2D plotting. To shift from an isometric to a perspective projection (with opening angle 60°) activate:
OPT += -DPERSPECTIVE
In order to modify the perspective calculation to produce a fish-eye style image, additionally activate:
OPT += -DFISHEYE
For use only with both perspective and fish-eye calculations, to shift the focus of the image to a declination of 60° (to appear at eye-level in the Scitech planetarium) use:
OPT += -DSCITECH_TILT