uclrits/purify repository overview

⁠PURIFY

⁠Description

PURIFY is an open-source collection of routines written in C++ available under the license⁠ below. It implements different tools and high-level to perform radio interferometric imaging, i.e. to recover images from the Fourier measurements taken by radio interferometric telescopes.

PURIFY leverages recent developments in the field of compressive sensing and convex optimization. Low-level functionality to solve the resulting convex optimisation is factored into the open-source companion code, SOPT⁠, also written by the authors of PURIFY. For further background please see the reference⁠ section.

This documentation outlines the necessary and optional dependencies⁠ upon which PURIFY should be built, before describing installation⁠, testing⁠ and usage⁠ details. Contributors⁠, references⁠ and license⁠ information then follows.

⁠Dependencies installation

PURIFY is written in C++11. Pre-requisites and dependencies are listed in following and minimal versions required are tested against Travis CI meaning that they come natively with OSX and the Ubuntu Trusty release. These are also the default ones fetched by CMake (an internet connection is required for this).

C++ minimal dependencies:

• CMake⁠ v3.5.1 (Trusty as cmake3) A free software that allows cross-platform compilation
• GCC⁠ v7.3.0 GNU compiler for C++
• UCL/GreatCMakeCookOff⁠ Collection of CMake recipes. Downloaded automatically if absent
• Boost⁠ v1.54 (Trusty). A set of free peer-reviewed portable C++ libraries. V1.65 downloaded automatically if absent but needs a cmake >= 3.9.2.
• fftw3⁠: Fastest Fourier Transform in the West
• Eigen3⁠ v3.3.7 (Trusty) Modern C++ linear algebra. Downloaded automatically if absent.
• tiff⁠ v4.0.3 (Trusty) Tag Image File Format library
• astro-informatics/sopt⁠ v* Sparse Optimization Compressed Sensing library. Downloaded automatically if absent.
• cfitsio⁠ v* Library of C and Fortran subroutines for reading and writing data files in FITS (Flexible Image Transport System) data format. Downloaded automatically if absent.
• casacore⁠ - Optional - Needed to interface with measurement sets. The main purify program requires this library (and its dependencies)
• OpenMP⁠ v4.8.4 (Trusty) - Optional - Speeds up some of the operations.
• MPI⁠ v3.1.1 (Trusty) - Optional - Parallelisation paradigm to speed up operations.
• spdlog⁠ v* - Optional - Logging library. Downloaded automatically if absent.
• Catch2⁠ v2.3.0 - Optional - A C++ unit-testing framework only needed for testing. Downloaded automatically if absent.
• google/benchmark⁠ v1.3.0 - Optional - A C++ micro-benchmarking framework only needed for benchmarks. Downloaded automatically if absent.

⁠Installing and building PURIFY

PURIFY can be installed through the software packet manager on Linux Debian distributions:

apt-get install purify

Alternatively, you can build PURIFY entirely from the source code. Once the mandatory dependencies are present, git clone from the GitHub repository⁠:

git clone https://github.com/astro-informatics/purify.git

Then, the program can be built with standard CMake command:

cd /path/to/code
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make

To test everything went all right:

cd /path/to/code/build
ctest .

To install in directory /X, with libraries going to `X/' do:

cd /path/to/code/build
cmake -DCMAKE_INSTALL_PREFIX=/X ..
make install

⁠Testing

To check everything went all right, run the test suite:

cd /path/to/code/build
ctest .

⁠Usage

The main purify executable lives either in the build directory or in the in the bin subdirectory of the installation directory. purify has one required argument, it a string for the file path of the config file containing the settings.

purify path/to/config.yaml.

A template with a description of the settings⁠ is included in the data/config directory.Whenpurify` runs a directory will be created, and the output images will be saved and time-stamped. Additionally, a config file with the settings used will be saved and time-stamped, helping for reproducibility and book-keeping.

⁠Docker

If you want to use Docker instead, you can build an image using the Dockerfile available in the repository or pulling it from DockerHub⁠.

docker build -t purify .

or

docker pull uclrits/purify

Then to use it, you should mount the directory with your data and config files to /mydata in the container. To run the container and mount the directory is with:

docker run -it --name purify -v /full/path/to/data:/mydata uclrits/purify

That will start a shell inside the container in the /mydata directory where you can see all the files from your /full/path/to/data. There you can run purify as shown above.`

⁠Contributors

Check the [contributors](@ref purify_contributors) page (github⁠).

⁠References and citation

If you use PURIFY for work that results in publication, please reference the webpage⁠ and our related academic papers:

1. L. Pratley, et al. "Distributed convex optimization for Radio Interferometry with PURIFY". Link will be here soon!
2. L. Pratley, M. Johnston-Hollitt, J. D. McEwen, "A fast and exact w-stacking and w-projection hybrid algorithm for wide-field interferometric imaging". Submitted to ApJ arXiv:1807.09239⁠
3. L. Pratley, J. D. McEwen, M. d'Avezac, R. E. Carrillo, A. Onose, Y. Wiaux. "Robust sparse image reconstruction of radio interferometric observations with PURIFY". Accepted (2016) arxiv:1610.02400⁠
4. A. Onose, R. E. Carrillo, A. Repetti, J. D. McEwen, J.-P. Thiran, J.-C. Pesquet, and Y. Wiaux. "Scalable splitting algorithms for big-data interferometric imaging in the SKA era" Mon. Not. Roy. Astron. Soc. 462(4):4314-4335 (2016) arXiv:1601.04026⁠
5. R. E. Carrillo, J. D. McEwen and Y. Wiaux. "PURIFY: a new approach to radio-interferometric imaging". Mon. Not. Roy. Astron. Soc. 439(4):3591-3604 (2014) arXiv:1307.4370⁠

⁠CMake Tips

It is possible to tell CMake exactly which libraries to compile and link against. The general idea is to add -DVARIABLE=something to the command-line arguments of CMake. CMake can be called any number of times: previous settings will not be overwritten unless specifically requested. Some of the more common options are the following:

• CMAKE_PREFIX_PATH: CMake will look in "CMAKE_PREFIX_PATH/lib" for libraries, "CMAKE_PREFIX_PATH/include" for headers, etc.
• FFTW3_LIBRARIES, FFTW3_INCLUDE_DIR
• BLAS_INCLUDE_DIRS, BLAS_LIBRARIES

All these variables and more can be found and modified in the CMakeCache.txt file in the build directory. There are extra CMake options sepcific to purify. -Ddompi=ON will turn MPI on in the build, -Dopenmp=ON will turn openmp on for the build. -Dtests=ON will make sure tests are built.

ctest should be run to make sure the unit tests pass.

⁠License

⁠Webpage

• Documentation⁠
• Repository⁠

⁠Support

For any questions or comments, feel free to contact Jason McEwen⁠, or add an issue to the issue tracker⁠.

⁠Notes

The code is given for educational purpose. The code is in beta and still under development.