================================================================================
Title: Fast Calculation of the Lomb-Scargle Periodogram 
       Using Graphics Processing Units  
Author: Townsend R.H.D.
================================================================================
Code names: culsp and lsp

Language: ISO C99 and CUDA C

Code tested under the following compilers/operating systems:

  Gentoo Linux 2.6.34 x86_64
  gcc 4.4.3
  CUDA SDK 3.1

Description of input data: 

  Two-column numeric ASCII: <time> <data>

Description of output data: 

  Two-column numeric ASCII: <frequency> <periodogram>

System requirements: 

  A CUDA-capable NVIDIA graphics processing unit

Calls to external routines: 

  Routines from the CUDA SDK
  libargtable2 library

Additional comments: 

Overview
--------

This package contains the source for the programs described in the
paper "Fast Calculation of the Lomb-Scargle Periodogram using Graphics
Processing Units" (Townsend, 2010). The source is distributed under
the GNU General Public License; see the file COPYING for details.

CULSP
-----

The 'culsp' subdirectory contains the source for the GPU-based CULSP
periodogram code. To compile this code, you will need release 3.1 (or
similar) of the NVIDIA CUDA Software Development Kit (SDK), which can
be obtained from http://developer.nvidia.com/object/gpucomputing.html
(compilation may work with other versions of the SDK, but this hasn't
been tested). 

You will also need a recent (4.x) version of the GNU gcc C compiler;
and the libargtable2 library and headers, which can be obtained from
http://argtable.sourceforge.net/.

Copy the entire 'culsp' subdirectory into the '<SDK>/C/src' directory
of the CUDA SDK (here, '<SDK>' indicates the filesystem path to the
SDK). Then, change into the '<SDK>/C' directory, and build the code
using the 'make' command. The resulting executable will be placed in
'<SDK>/bin/<platform>/release', where '<platform>' is the name of your
computer platform (e.g., linux, darwin, etc).

To run the code, use the following command:

culsp --in=<in_file> --out=<out_file> --over=<F_over> --high=<F_high>

...where:

  <in_file> is the name of the input light curve file, comprising
  lines with space-separated time/data pairs

  <out_file> is the name of the output periodogram file, comprising
  lines with space-separated frequency/periodogram pairs

  <F_over> is the frequency oversampling parameter discussed in the
  paper

  <F_high> is the frequency extent parameter discussed in the paper

For platforms hosting multiple CUDA-capable GPUs, you can select which
device to run on using the optional '--device=<dev_num>' argument,
where <dev_num> (= 0, 1, 2, ...) is the index of the device. You can
also suppress the prompt at the end of execution using the optional
'--no-prompt' argument.

LSP
---

The 'lsp' subdirectory contains the source for the CPU-based LSP
periodogram code. To compile this code, you will need a recent (4.x)
version of the gcc C compiler. You will also need the libargtable2
library and headers installed on your system, which can be obtained
from http://argtable.sourceforge.net/.

Change into the 'lsp' subdirectory, and build the code using the
'make' command.

To run the code, use the following command:

lsp --in=<in_file> --out=<out_file> --over=<F_over> --high=<F_high>

...where the arguments have the same meaning as above for CULSP.

================================================================================
The AAS gives permission to anyone who wishes to use these subroutines
to run their own calculations.  Permission to republish or reuse these
routines should be directed to the Executive Officer of the AAS.

Note that the AAS does not take responsibility for the content of the 
source code.  Potential users should be wary of applying the code
to conditions that the code was not written to model and the accuracy of
the code may be affected when compiled and executed on different systems.
================================================================================

