Sparse2D

Sparse2D provides an array of sparsity-based signal processing tools and a convenient C++ library for performing various wavelet transforms.

You can find out more about the applications of Sparse2D on the CosmoStat website.

The core Sparse2D libraries are used as a backend for PySAP.

Docker installation

Pull the Docker image

If you have Docker installed, you can pull the latest build of the Sparse2D image as follows:

docker pull ghcr.io/cosmostat/sparse2d:master

No further installation is required.

Run a Docker container

To run a container on data in your current working directory, simply run:

docker run -v ${PWD}:/workdir --rm ghcr.io/cosmostat/sparse2d:master <EXECUTABLE> <ARGUMENTS>

where <EXECUTABLE> is one of the Sparse2D binaries and <ARGUMENTS> are the corresponding command line arguments for this executable. The reference to ${PWD} can be replaced by the path to any directory on your system.

For example, to run a bspline wavelet transform on a FITS image called myfile.fits you would run:

docker run -v ${PWD}:/workdir --rm ghcr.io/cosmostat/sparse2d:master mr_transform -t 2 myfile.fits myoutput.mr

Tip: If you don't want to constantly write the full Docker run command you can create an alias e.g.:

alias sparse2d="docker run -v ${PWD}:/workdir --rm ghcr.io/cosmostat/sparse2d:master"

then you can simply run e.g.:

sparse2d mr_transform -h

Launch a Jupyter notebook

You can also run a Jupyter notebook with a Docker container as the backend in order to use the pysparse Python bindings to some Sparse2D tools.

docker run -p 8888:8888 -v ${PWD}:/workdir --rm ghcr.io/cosmostat/sparse2d:master notebook

Homebrew installation

Standard installation

Sparse2D can be installed on macOS using Homebrew.

brew tap cosmostat/science
brew install sparse2d

The Homebrew formula handles all of the required dependencies.

Build options

By default, the Homebrew formula builds the full Sparse2D package including the pysparse Python bindings. Some options are available to limit of the scope of the build. These options can be listed as follows (after tapping cosmostat/science):

brew info sparse2d

Python bindings

The pysparse bindings will be saved to /sparse2d/python in your Homebrew directory (i.e. /usr/local/opt for macOS with Intel or /opt/homebrew for macOS with Apple silicon). You will need to add this to your PYTHONPATH in order to access the bindings. For example, for a recent Apple computer you would run the following:

export PYTHONPATH="/opt/homebrew/sparse2d/python:$PYTHONPATH"

Note that pysparse will be built using the Python executable installed by Homebrew. These bindings will only work with the same version of Python.

Building from Source

Dependencies

In order to build Sparse2D from source, you will need to ensure you have installed all of the following dependencies. If possible, please use a package management tool to properly install them (e.g. apt on Ubuntu or brew on macOS).

Required

• C/C++ compiler (e.g. gcc or clang)
• CMake (>= v3.12)
• CFITSIO
• pkg-config

Optional

• Armadillo (not required if ONLY_SPARSE=ON or ONLY_INPAINT=ON)
• BigMac (only required if using macOS clang)(>= v0.0.6)
• Catch2 (only required for unit tests)(>= v3)
• FFTW (not required if ONLY_SPARSE=ON and USE_FFTW=OFF)
• GSL (not required if ONLY_SPARSE=ON)
• HEALPix (not required if ONLY_SPARSE=ON or ONLY_INPAINT=ON)
• libomp (only required if using macOS clang)
• Pybind11 (not required if BUILD_PYBIND=OFF or ONLY_INPAINT=ON)
• Python (not required if BUILD_PYBIND=OFF or ONLY_INPAINT=ON)

Full Sparse2D build

Download the latest release of Sparse2D.

Create a build directory inside the root directory of the Sparse2D package:

cd Sparse2D
mkdir build
cd build

Build Sparse2D:

cmake ..
make
make install

Tip: You can significantly increase the speed of compilation by using the --jobs (or -j) option for make, which builds the targets in parallel. For example, to use 8 cores you would run make -j 8.

Build options

Sparse2D supports the following CMake build options:

• BUILD_MSVST (default ON): Build the MSVST package
• BUILD_MISC (default ON): Build the MISC package
• BUILD_MR (default ON): Build the MR package
• BUILD_MC (default ON): Build the MC package
• BUILD_MGA (default ON): Build the MGA package
• BUILD_MWIR (default ON): Build the MWIR package
• BUILD_DICLEARN (default ON): Build the DICLEARN package
• BUILD_MRS (default ON): Build the MRS package
• BUILD_ASTRO_WL (default ON): Build the ASTRO_WL package
• BUILD_ASTRO_GAL (default ON): Build the ASTRO_GAL package
• BUILD_PYBIND (default ON): Build Python bindings
• ONLY_SPARSE (default OFF): Only build the SPARSE package
• ONLY_INPAINT (default OFF): Only build the packages required for inpainting
• USE_FFTW (default ON): Use FFTW libraries (optional for sparse package only)
• BUILD_CFITSIO (default OFF): Build CFITSIO from source
• BUILD_FFTW3 (default OFF): BUILD FFTW3 from source
• BUILD_HEALPIX (default OFF): BUILD HEALPix from source
• BUILD_GSL (default OFF): BUILD GSL from source (not implemented)
• BUILD_DEPS (default OFF): BUILD all dependencies from source

To use these options prepend -D when running the cmake command, e.g.:

cmake .. -DONLY_SPARSE=ON

Non-default compiler

Finally, if you wish to build using a compiler other than the default on your system (e.g. gcc on macOS) you can do so as follows:

CC=gcc CXX=g++ cmake ..

Python bindings

By default Sparse2D will build pysparse, which includes Python bindings to some Sparse2D tools. This file will need to be in your PYTHONPATH in order for these bindings to available outside of the build directory. You can manually specify an install location for this file passing the option PYBIND_INSTALL_PATH to CMake, e.g.:

cmake .. -DPYBIND_INSTALL_PATH=<path to your Python environment>

pysparse can be imported in a given Python session as follows:

import pysparse

To see what tools are available in this module run the help function.

help(pysparse)

For example, to run a bspline wavelet transform on an image (stored in memory as a Numpy array) called myimage you would run:

import pysparse
mrt = pysparse.MRTransform(2)
result = mrt.transform(myimage)