Updated docs for v2

INSTALL

@@ -11,22 +11,21 @@ Basic steps to install:
   your machine, --prefix=/usr/local is the default for FFTW and
   is a safe bet).
 
-  If you have a modern version of GCC installed (v3.2 or better) 
-  and a modern CPU (Intel Pentium IV, or newer; AMD Opteron 
-  or better, G5), you can get _drastically_ better performance by
-  adding the following options:
+  If you are on a modern Intel processor and have a recent version
+  of GCC, you can get much improved performance by adding:
+  --enable-sse2 --enable-avx
 
-  For Intel PIVs or later, EM64Ts, or AMD64s:
-  --enable-sse
-
-  For Mac G5s:
-  --enable-altivec
+  Note that Ubuntu has good FFTW packages now.
 
 2.  Install PGPLOT.  http://www.astro.caltech.edu/~tjp/pgplot/
   You need the X-windows and postscript drivers at a minimum.
+  Note that on 64-bit systems, compiling and linking PGPLOT can
+  be tricky!
+
+  Note that Ubuntu has good PGPLOT packages now.
 
 3.  Install TEMPO.  Make sure to set the TEMPO environment variable.
-  http://pulsar.princeton.edu/tempo/index.html
+  http://tempo.sourceforge.net/
 
 4.  Install GLIB (v2.X). 
   http://library.gnome.org/devel/glib/ On Linux machines this 
@@ -35,13 +34,17 @@ Basic steps to install:
   glib development package in order to have the required include 
   files...
 
+  On Ubuntu, the package you need is: libglib2.0-dev
+
 5.  Install CFITSIO.
   http://heasarc.gsfc.nasa.gov/fitsio/
   This is a very easy install and is now needed since PSRFITS
   is now being written by several pulsar instruments (Nice!
   a pulsar data standard that external tools can actually
   view!  How about that!)
 
+  Once again, Ubuntu has CFITSIO packages!
+
 6.  Define the PRESTO environment variable to the top level
   directory of the PRESTO distribution (i.e. this directory).
 
@@ -55,8 +58,7 @@ Basic steps to install:
   only user on the machine when you run this, as it is very
   computation intensive and may take a while.
 
-9.  Just for safety's sake (and because SVN sometimes messes up
-  file access times), do a "make prep".  That will make sure
+9.  Just for safety's sake, do a "make prep".  That will make sure
   that make does not try to run Clig to re-generate all of the
   command line interface files.
 
@@ -77,15 +79,17 @@ Basic steps to install:
 
 13.  If you want to use all the python routines (which if you are
   doing anything but the most rudimentary analyses you will want 
-  to), you need Python >= version 2.3, and the _new_ Numpy/SciPy.  
-  You can get Numpy/Scipy here:  http://www.scipy.org/download/
-  I recommend using the Subversion versions (and for PRESTO 
-  as well).  In general, the following should work:
+  to), you need Python >= version 2.3, and Numpy/Scipy
+  http://www.numpy.org  and  http://www.scipy.org
+  In general, the following should work:
      "cd $PRESTO/python ; make ; make fftfit"
   If it doesnt, you will probably need to edit the Makefile 
   or setup.py.
 
 14.  Go find pulsars!
 
+Note for Mac users having problems: Paul Ray has been running PRESTO a
+lot and knows the tricks to get it working...
+
 Scott Ransom
-Mar 2009
+Jan 2014

README.md

@@ -0,0 +1,146 @@
+# PRESTO v2
+
+http://www.cv.nrao.edu/~sransom/presto/
+
+PRESTO is a large suite of pulsar search and analysis software
+developed by Scott Ransom mostly from scratch.  It was primarily
+designed to efficiently search for binary millisecond pulsars from
+long observations of globular clusters (although it has since been
+used in several surveys with short integrations and to process a lot
+of X-ray data as well).  It is written primarily in ANSI C, with many
+of the recent routines in Python.  According to Steve Eikenberry,
+PRESTO stands for: PulsaR Exploration and Search TOolkit!
+
+## New in this release:
+ * WAPP, BCPM, Spigot, and 1-bit analog filterbank data are deprecated! 
+   (see below)
+ * Dramatically improved internal handling (giving better dynamic
+   range and RFI removal) of PSRFITS and SIGPROC filterbank data
+ * Massive speed-ups (factors of 2 or more) of `accelsearch` when
+   all of the F-Fdot plane can fit into core memory (that can be set
+   by changing values in `include/meminfo.h`)
+ * Many bug fixes and several new scripts (including new orbit fitters)
+
+PRESTO is written with portability, ease-of-use, and memory efficiency
+in mind, it can currently handle raw data from the following pulsar
+machines or formats:
+
+ * PSRFITS search-format data (as from GUPPI at the GBT, PUPPI and
+   the Mock Spectrometers at Arecibo, and much new and archived data
+   from Parkes
+ * 1-, 2-, 4-, 8-, and 32-bit (float) filterbank format from SIGPROC
+ * A time series composed of single precision (i.e. 4-byte) 
+   floating point data
+ * Photon arrival times (or events) in ASCII or double-precision 
+   binary formats
+
+Notice that the following formats which *used* to be supported are not:
+
+ * Wideband Arecibo Pulsar Processor (WAPP) at Arecibo
+ * The Parkes and Jodrell Bank 1-bit filterbank formats
+ * SPIGOT at the GBT (may it RIP...)
+ * Berkeley-Caltech Pulsar Machine (BCPM) at the GBT (may it RIP...)
+
+If you need to process them, you can either checkout the "classic"
+branch of PRESTO, which is not being actively developed.  Or you can
+use `DSPSR` to convert those formats into SIGPROG filterbank format
+(and/or maybe someday soon, PSRFITS search format).  You can grab
+DSPSR [here](http://dspsr.sourceforge.net).  If you *really* need to
+get one of these machines working in PRESTO v2, let me know and we can
+probably make it happen.  It will take a day or two of porting for
+each backend.
+
+The software is composed of numerous routines designed to handle three
+main areas of pulsar analysis:
+
+1. Data Preparation: Interference detection (`rfifind`) and removal
+   (`zapbirds`) , de-dispersion (`prepdata`, `prepsubband`, and
+   `mpiprepsubband`), barycentering (via TEMPO).
+
+2. Searching: Fourier-domain acceleration (`accelsearch`), single-pulse
+   (`single_pulse_search.py`), and phase-modulation or sideband searches
+   (`search_bin`).
+
+3. Folding: Candidate optimization (`prepfold`) and Time-of-Arrival
+   (TOA) generation (`get_TOAs.py`).
+
+4. Misc: Data exploration (`readfile`, `exploredat`, `explorefft`),
+   de-dispersion planning (`DDplan.py`), date conversion (`mjd2cal`,
+   `cal2mjd`), tons of python pulsar/astro libraries, average pulse
+   creation, flux density estimation, and more...
+
+Many additional utilities are provided for various tasks that are
+often required when working with pulsar data such as time conversions,
+Fourier transforms, time series and FFT exploration, byte-swapping,
+etc.
+
+The Fourier-Domain acceleration search technique that PRESTO uses in
+the routine accelsearch is described in [Ransom, Eikenberry, and
+Middleditch
+(2002)](http://adsabs.harvard.edu/abs/2002AJ....124.1788R), and the
+phase-modulation search technique used by search_bin is described in
+[Ransom, Cordes, and Eikenberry
+(2003)](http://adsabs.harvard.edu/abs/2003ApJ...589..911R).  Some
+other basic information about PRESTO can be found in my
+[thesis](http://www.cv.nrao.edu/~sransom/ransom_thesis_2001.pdf).  I
+will eventually get around to finishing the documentation for PRESTO,
+but until then you should know that each routine returns its basic
+usage when you call it with no arguments.  I am also willing to
+provide limited support via email or telephone (434-296-0320).
+
+Tutorial(!): Note that in the "docs" directory there is a now a
+tutorial which walks you through all the main steps of finding pulsars
+using PRESTO.
+
+To date, PRESTO has discovered well over two hundred pulsars,
+including more than 120 recycled pulsars, most of which are in
+binaries!
+
+## Getting it: 
+The PRESTO source code is released under the GPL and
+can be browsed or gotten from here in many different ways
+(including zipped or tar'd or via git).  If you are too lazy to
+read how to get it but have git on your system do:
+
+> git clone git://github.com/scottransom/presto.git
+
+To update it on a regular basis do
+
+> cd $PRESTO
+> git pull
+
+and then re-make things in $PRESTO/src. 
+
+For more detailed installation instructions, see INSTALL.
+
+If you don't want to mess with git (which means that you will need to
+re-install a tarball whenever there are updates) you can get it from
+the "Download Source" link on the github page.
+
+If you plan to tweak the code, I highly suggest that you use git and
+clone the directory (or fork it using an account on github).  Read the
+following "living document" on how to develop and collaborate in a
+relatively sane way using git:
+  http://docs.scipy.org/doc/numpy/dev/gitwash/index.html
+If you plan on doing any significant development, please let me know
+and I'll either add you as a developer, or we can push/pull changes
+via git/github (see the "gitwash" document above).  Code contributions
+and/or patches to fix bugs are most welcome!
+
+Final Thoughts: Please let me know if you decide to use PRESTO for any
+"real" searches.  And if you find anything with it, it would be great
+if you would cite either my thesis or whichever of the two papers
+listed above is appropriate.  Thanks!
+
+Acknowledgements: Big thanks go to Steve Eikenberry for his help
+developing the algorithms, Dunc Lorimer for the basic code which is
+used to process BCPM and WAPP data, David Kaplan for lots of help with
+the GBT SPIGOT code, Jason Hessels for many contributions to the
+Python routines (and along with Maggie Livingstone for the rednoise
+reduction routine), Anne Archibald (for significant help with the
+recent accelsearch improvements), and Paul Demorest, Paul Ray, Ingrid
+Stairs, Fernando Camilo, Cees Bassa, Patrick Lazarus, Mike Keith,
+Slavko Bogdanov, and Paulo Freire for many comments and suggestions
+(and even some patches!).
+
+Scott Ransom <[email protected]>