Home
Name Modified Size InfoDownloads / Week
supplementary 2019-02-12
obsolete 2016-06-03
README 2017-03-23 11.8 kB
hammurabi_v3.01.tar.gz 2016-08-01 984.3 kB
Totals: 4 Items   996.2 kB 0
April 2016


This README describes the Hammurabi code for simulating astrophysical emission such as diffuse polarized synchrotron and dust emission as well as Faraday rotation measures based on models for the magnetized interstellar medium.  It is written in C++, tested on Linux and OSX, and depends on the following libraries:  HEALPix C++;  NE2001 (Fortran);  GSL;  FFTW.  


Summary of changes since the previous release:  

     - Added the ability to give inputs for the B-field or TE as a Cartesian grid that is rotated to align along a specified (lon,lat) direction and centered at a distance R along that LOS.  This is useful for simulating a particular object rather than the entire Galaxy. 

     - Added the ability to compute the RM and synchrotron emission analytically as the ensemble average of the model, following the method of Jansson & Farrar (2012).   Warning:  things can be subtle.  This method gives you the correct average Q and average U but not the correct average polarized intensity.  (P is basically a random walk, and the larger the random component, the larger the P can deviate, which is *not* taken into account by the analytic method.)  This analytic method does not apply to dust emission, as it relies on the assumption that the emissivity goes as B^2.  

     - Added the possibility to link the code with a slightly modified version of Galprop.  This allows you to use the same hammurabi B-field in the CR propagation and then use the resulting CR distribution in the synchrotron computation in hammurabi.  

     - The Makefile  now defines four executables that can be built:

     *  hammurabi:  	  	by default, the basic hammurabi, pure C++, for constant or grid TEs and simple analytic models for CREs
     *  hammurabi.ne2001:  	including linking to the (modified, smooth) NE2001 Fortran code using cfortran.h
     *  hammurabi.galprop:	including both NE2001 and Galprop to simulate the CRE propagation with the hammurabi magnetic field first.
     *  hammurabi.debug:  	including both options, debug flags.

     - For integration over a pixel list (as opposed to a full-sky map), it now uses the HEALPix functions for 64-bit integers, allowing for Nside > 2^13 and up to 2^29.  This is not to be used for maps (which would be prohibitive) but for pixel lists of patches of the sky. 

    - Fixed a bug in the deflection angles, thanks to G. Farrar et al..  Previous versions had an incorrect sign of the deflection.  

    - Fixed bug in synchrotron normalization by a  factor of 2, thanks to M. Unger.  Previous versions produced synchrotron emission a factor of 2 higher than was correct for the given CRE density and B-field strength.  


Known issues:
 
      - There is a known problem running hammurabi linked with the NE2001 Fortran code and gfortran (both 4.3.6 on OSX and 4.4.7 on linux), which results in a run-time error from Fortran.  If you do not need the NE2001 code itself, then build the basic hammurabi  that does not link it.  With this version, you can still input the NE2001 model using a pre-generated Cartesian grid found on the hammurabi web site.  Alternatively, build the code with the NE2001 code but set the debugging flags;  this appears to avoid the problem, which may be related to optimization.  (I.e. edit the Makefile and change -O2 to -g.)


--------------------------------------------------------------------------------
--------------------------------------------------------------------------------

Installing hammurabi:

1) Install the dependencies:  FFTW, Cfitsio, HEALPix (C++), and GSL.  (This version is tested with fft2 3.2.2 or 3.3.4, cfitsio3370, HEALPix 3.11 or 3.20, and gsl 1.13.)  Note that these dependencies should be built with the same compilers you will use for hammurabi.  For Mac users, do not use the MacPorts build of HEALPix, because this does not install all of the necessary libraries hammurabi links to;  you have to get the full HEALPix and build it yourself.  

2) Expand (e.g., gunzip) the hammurabi package in a separate directory.  

3) Make sure your HEALPix environment is set correctly, e.g.

setenv HEALPIX_TARGET generic_gcc
setenv HEALPIX /Users/tj/space/sw/healpix/Healpix_3.20

4) Edit the Makefile to select the correct options for your compilers and point to the installed dependencies.  This version has been tested on:   linux with gcc 4.4.7 (using the included gfortran for NE2001);  Mac OSX with MacPorts gcc 4.3 (using the included gfortran).

5)    make hammurabi

Even if you wish to build one of the other executables, first make the basic C++ hammurabi to test before trying the others.  

The executables are placed in a subdirectory called run.  

6)  Then for each compilation of a different executable, run, e.g., 

  make clean;  make hammurabi.ne2001

  to cleanup any previous run. (Note that this cleans .o and .a files but leaves the resulting executables in the run subdirectory.  So you can do, e.g., 'make hammurabi; make clean; make hammurabi.ne2001" and you'll have both executables in the run directory at the end.

7)  For a simple test, use the test_params.txt parameter file, which will produce a synchrotron map of a trivial case. 


--------------------------------------------------------------------------------
--------------------------------------------------------------------------------

Installing hammurabi linked with Galprop:

This process is slightly more complicated because of the inter-dependencies of the two codes.  The modified version of Galprop depends on the hammurabi magnetic field module, while the hammurabi integration then clearly depends on the resulting Galprop CRE module.  Make sure the simple hammurabi compilation works and runs first.  

The version of Galprop included on the hammurabi site is a modified version of the Galprop found on 

https://sourceforge.net/projects/galprop

Specifically, it was taken from the tar file of revision 2766 of that repository.  (Note that this differs slightly from the version on http://galprop.stanford.edu.  I also tested with their version 54.1.984.)

The compilation is a bit sensitive to compiler versions, and you may have to experiment with changing the orders of some of the flags.  What is included in this release is what worked for gcc 4.4.7 on Linux or gcc 4.3.6 on OSX.


1)  In addition to the hammurabi dependencies above, install CCfits and CLHEP.   (This version is tested with CCfits-2.2 and CLHEP 2.0.4.5.)  Note that these dependencies should be built with the same compilers you will use for Galprop and hammurabi.  


2)  In the hammurabi  directory, build the library that will be needed by Galprop:

  make clean; make libhamprop.a


3) Expand (e.g., gunzip) the customized Galprop package in a separate directory.  Then in the Galprop directory, compile Galprop itself.  First, set the environment needed by its autoconfigure script.  E.g., 

  setenv CC "gcc-mp-4.3 -m64"
  setenv CXX "g++-mp-4.3 -m64"
  setenv F77 gfortran-mp-4.3
  setenv FC gfortran-mp-4.3
  setenv CPP cpp-mp-4.3
  setenv CXXCPP cpp-mp-4.3

Now following the Galprop instructions with a few modifications:


4)  autoreconf -i -v -f


5) Edit the source/Makefile.am to set the path to hammurabi and fftw on lines 11 and 14.


6) After changing this for the correct paths to cfitsio, CCfits, HEALPix, GSL, and CLHEP (for each dependency, the given directory should contain the lib and include subdirectories), then configure:  

  > ./configure --with-cfitsio=${HOME}/space/sw/cfitsio/cfitsio/build --with-ccfits=${HOME}/space/sw/CCfits/CCfits/build --with-healpix=${HEALPIX_CXX}/${HEALPIX_TARGET} --with-gsl=${HOME}/space/sw/gsl/gsl-1.13/build/ --with-clhep=${HOME}/space/sw/clhep/2.0.4.5/CLHEP/build/ --prefix=${PWD}/build --with-galdef=./GALDEF/ --with-fitsdata=${PWD}/FITS/ --enable-openmp


7) and then build Galprop:

  make

  and if that succeeds, then 

  make install

  which just copies things to the build area.  

  At the end of the make step, the linking of the galprop executable itself often fails because the flags aren't all set correctly, or because the order can be important on some compilers.  If the libraries are built correctly (source/libgalprop.a and source/libskymap.a) but the linking fails, you will not have a galprop executable, but hammurabi should build fine anyway.  So if you have the files source/libgalprop.a and source/libskymap.a, that is all you really need for hammurabi.  They are installed in build/lib/ if the compilation goes all the way to the end, but you can copy them by hand if not.  Just make sure the hammurabi Makefile points to the directory containing them.   

(I've often had odd problems trying to link the galprop executable, with errors related to the openMP functions.  On OSX, adding -lgcc_eh to the link line seems to fix it.  Then run 'make' again to finish and then 'make install'.)


8)  Then, go back to the hammurabi directory and first clean then build the hammurabi.galprop executable:

  make clean ; make hammurabi.galprop

(The clean step is important!  The flags are different for libhamprop.a and hammurabi.galprop.)  


9) For running these, update the path for searching for dynamically loaded libraries so that CLHEP and CCfits are found.  For csh/tcsh following needs to go into the .cshrc or .tcshrc sourced at the opening of the session:  

   On OSX :

   setenv DYLD_LIBRARY_PATH "/path/to/clhep/build/lib/:/path/to/CCfits/build/lib/"

   while on Linux, it's

   setenv LD_LIBRARY_PATH "/path/to/clhep/build/lib/:/path/to/CCfits/build/lib/"

For bash, it's 

   setenv LD_LIBRARY_PATH="/paths..."

etc.


--------------------------------------------------------------------------------
--------------------------------------------------------------------------------

Testing hammurabi:

On the Sourceforge site can be found a tar file containing a set of "unit tests".  This consists of many different runs of hammurabi with different parameters designed to test various functions of the code, various test cases and contexts.  They are not meant to be physically realistic (many are completely unphysical) but simply to control for changes in the results.  This was also originally not meant to be public, so it's not terribly user friendly.  Suggestions welcome.  

Dependencies:

- all hammurabi targets must be built, including the versions linked with GALPROP and NE2001 codes as well as the debug version ("make all");  

- IDL, in order to create visualizations of the results;

- the HEALPix Fortran and IDL functions, so that the IDL wrappers for tools like anafast work;  

- gs, in order to convert PS files written by IDL into PNGs for visualizing on a simple web page (on my system, I have issues writing the images directly to PNG).


1)  Download the tar file for the tests and expand it in the directory where hammurabi is built.  It consists of a unit_test subdirectory that contains the inputs, parameter files, scripts, and reference outputs for comparison.  

2) Then from the main hammurabi directory, simply 

>  make test

Depending on the system and whether the code is built with openMP, this can take a long time (hours).  Before it starts running hammurabi, it checks your available memory.  If you have 3GB free memory, it runs the normal test, which includes some GRF simulations that require that much.  If not, it runs a mini-test, the largest of which requires about 1GB.  (Note that on OSX, things in memory are moved around dynamically, so the check may fail but the test would work fine if you tried.  If you want to force it, edit the unit_test/test.csh script.)

3) If it runs successfully, you can compare the outputs by comparing two web pages in your browser, each of which shows a few plots for each test case:

unit_test/ref/views/plots.html

versus

unit_test/out/views/plots.html









Source: README, updated 2017-03-23