Download and installation instructions
Important! Many of the tarballs on this page are sadly out of date. To keep up with the latest developments, you really should get access to the DiFX SVN repository. The easiest way to do this is to join the DiFX-Users group hosted at Google Groups and request access - to do this, follow this link and request to join. The information below contains useful information on how to install and configure DiFX, but the SVN code repository is kept much more up to date.
Firstly - we need to make a distinction between the program which actually does the work (mpifxcorr) and the graphical frontend (DiFXGUI). DiFXGUI is just a nice bit of Java code to make setup easier. Its pretty easy to install and get running. Mpifxcorr, on the other hand, depends on a bunch of other libraries, which can be a bit more challenging. So, to make things easier, I've provided some pre-built binaries for 32 bit 2.6.x linux kernels, running on x86 architectures with SSE2 instructions (includes Pentium 4, Athlon, Opteron etc). Regardless, start off by creating a directory somewhere to put your shiny new correlator code, and defining an environment variable CORR_ROOT to point at this directory.
If you just want the prebuilt binary, grab it here. Create a directory $CORR_ROOT/mpifxcorr/src/, and put it in there. If you don't want to install the source, skip down to the testing section and make sure it works (you may need to install MPI if you don't have it already - see below).
If you need to tinker with the source code, run on a different platform or tweak the compilation options, you'll need the mpifxcorr source and some other libraries, as well as an implementation of MPI. Running through them in order:
Okay, so now you have rpfits, ipp, vlba_utils and some kind of MPI all compiled and ready to go. What you need to do now is point mpifxcorr at these libraries and compile. So:
- MPI: You may well have this already installed - try looking for mpicc in your path. If you don't have any version of MPI installed, a good one to download is mpich. Follow the instructions on the webpage for installing this one.
- RPFITS: This is used to make the output files from the correlator. You can produce ascii output, but thats not much fun. I recommend installing this library in the directory $CORR_ROOT/rpfits/. You no longer need the additional file "rpfits_subroutines.h" - the latest version of RPFITS from the ATNF has tidied the code and made this extra header file redundant. If you use AIPS to post-process, you'll want to get atlod to load the rpfits files into AIPS - see here
- Intel Performance Primitives (IPP): This is your optimised vector library. Download the free 30 day trial, or buy it - its pretty cheap for non-commercial use. Put this one whereever - if you are root, you can install it somewhere logical like /opt/intel/... Otherwise, you'll probably need to add the library subdirectory to your LD_LIBRARY_PATH variable.
- VLBA utils: This utility library has been kindly provided by Walter Brisken and is used to unpack Mk5 data, in both Mk4 and VLBA style formats. I recommend unzipping and untarring it in $CORR_ROOT, that will automatically place it in a subdirectory called vlba_utils/. Just do a make.
- Mpifxcorr: The main program. Unzip and untar in $CORR_ROOT, and it will be placed in a subdirectory called mpifxcorr.
That's it! You should now be able to run mpifxcorr: test it with "mpirun -np 1 $CORR_ROOT/mpifxcorr/src/mpifxcorr", you should get an error message about invoking mpifxcorr with an input file.
- Edit $CORR_ROOT/mpifxcorr/src/Makefile.am and change the paths to any of the library and include files as appropriate.
- Go to $CORR_ROOT/mpifxcorr/
- Run aclocal
- Run automake
- Run ./configure CXX=/your/mpi/path/mpicxx
- cd src
DiFXGUI itself is nice and simple - however, it also manages the automatic creation of model files using CALC. So I'll give the pointers to all the required libraries, and if you're implementing your own model generation, you can ignore the CALC stuff.
- JMathPlot: This is a plotting library for java. Create a subdirectory of $CORR_ROOT called DiFXGUI and put it in there.
- DiFXGUI.jar: This is the java-based graphical frontend. Put it in $CORR_ROOT/DiFXGUI/ as well.
- COMMANDS.CONFIG: This provides the path to some utility programs for DiFXGUI. Put it in the same directory.
That's it for the basic frontend. Test with java -jar $CORR_ROOT/DiFXGUI/DiFXGUI.jar, and you should see a window pop up.
So now you can create input files for the correlator from scratch, and then go launch them manually. But you want to generate model information, select nodes to run on and create your basic input files directly from vex files don't you? If so, keep going to get and install all this ancillary stuff.
- CALC: This forms part of a larger package called CALC/SOLVE which has been developed at Goddard Space Flight Centre and is available from their website at http://gemini.gsfc.nasa.gov/solve/. However, we only want a subset of this code, which has been slightly extended to facilitate our purpose of generating geocentric VLBI delays in a stand-alone fashion. Therefore I've put together this calc9.tar.gz tarball which you can download.
Its worth mentioning that if you want to use your own model generating code, just take a look at the format of the .delay and .uvw files contained in the ascii examples tarball and you should be able to write a translator program to produce precomputed delays in this format, without using this version of CALC.
- Create a directory for this to reside in (I use $CORR_ROOT/calc/)
- Define the environment variable CALCDB to point at this directory
- Copy the tarball there.
- Extract the files (gunzip calc9.tar.gz; tar -xvf calc9.tar)
- Run make
- Create a static library with the command "ar -r libcorcalc.a *.o". That's it!
- Astro::VEX: You will need a c vex library, vex.tar.gz, as well as the perl vex parser and some miscellaneous perl astro routines called Astro-0.69. Download these three, create a directory $CORR_ROOT/vexparser/ and untar them in there. You should be able to just make the vex library, then edit Makefile.PL from the vex parser library to point towards the newly created library, and compile both perl modules with the following steps (ie repeat once for the vexparser and once for Astro-0.69):
finally, you need to set up the PERL5LIB environment variable (the perl equivalent of LD_LIBRARY_PATH): setenv PERL5LIB $CORR_ROOT/vexparser/something/perl/lib/:$CORR_ROOT/vexparser/Astro-0.69/something/perl/lib/ ! Use the correct paths here, to the directories which contain the files Vex.pm, Time.pm etc - the "something" will probably be something like lib/perl5/site-perl/5.8.5/.../ - it depends on the perl version amongst other things
- perl Makefile.PL PREFIX=$CORR_ROOT/vexparser/
- make install
- utilities: These are the programs I have writting using the CALC and Astro::VEX libraries to automatically produce model files and correlator input files based on the vex files used to schedule the experiment. Untar in $CORR_ROOT, this will create a subdirectory called utilities. Enter that directory and type make - thats all! The $CALCDB/ environment variable must be set, however.
So now you have all the ancillary programs, you need to ensure the DiFXGUI is correctly pointed at them. Have a look at COMMANDS.CONFIG which you downloaded earlier, and compare the listing of commands to the contents of the $CORR_ROOT/utilities/ directory. They should all be there. If you wish to use a different program for any of the commands listed in COMMANDS.CONFIG, just change it there and put the program in the utilities/ subdirectory. Now, you will probably want to change at least the GETNODELIST, GETPBSNODELIST, GETQUEUES, and QUEUE GATEWAY entries, as these were specific to the Swinburne cluster setup. Use the existing perl scripts as a guide, and contact me for more details if you need. If you aren't using a pbs queueing system (and if you've never heard of it then you're not), you can just put dummy scripts and values in for the last three items I mentioned above.
The last thing you'll probably want to do is to put the new environment variable and execution paths into your login script (eg ~/.cshrc if you're using csh). I set CORR_ROOT, CALCDB, and add $CORR_ROOT/mpifxcorr/src/ and $CORR_ROOT/utilities/ to my PATH variable (also add the mpi bin/ subdirectory if its installed in a non-standard area). Anything you found you had to add to your LD_LIBRARY_PATH along the way, you may as well put in here too in case you want to recompile things at a future date. Also update the PERL5LIB variable to include the vex parser directory.
That's it! Fire up DiFXGUI, make sure you can create some model files and some input files, and/or take a look at the examples provided in the ascii examples tarball and data examples tar file and try launching some jobs! You'll find all the instructions on the "Running DiFX" page.