This is version 2 of the HI Source Finding Application (SoFiA). SoFiA 2 is a reimplementation of the original SoFiA pipeline in the C programming language. It is intended for use in HI data analysis pipelines and will be developed and maintained in parallel to SoFiA 1.x. While SoFiA 2 is still under active development, a stable release is already available at this point in time and can be used in production mode. In addition, users will be able to continue using SoFiA 1.x (https://github.com/SoFiA-Admin/SoFiA) for processing their data.

• Being written in C and making extensive use of multi-threading, SoFiA 2 is much faster than SoFiA 1.x.
• SoFiA 2 requires significantly less memory than SoFiA 1.x (down from > 5 × cube size to ~ 2.3 × cube size).
• SoFiA 2 currently has only a single external dependency (wcslib) and should therefore compile and run on any machine with a Linux or Unix operating system and the GCC compiler and wcslib installed.

Please ensure that the GNU C compiler (GCC) and WCSLIB (https://www.atnf.csiro.au/people/mcalabre/WCS/) are installed on your machine, before downloading and extracting the SoFiA 2 source code into a directory of your choice. You may want to first check if WCSLIB is either already installed or available from your operating system’s software repository (wcslib-dev package on Ubuntu/Debian; wcslib-devel on Fedora/CentOS/Red Hat; wcslib on MacOS/Homebrew) before attempting to install it manually.

Both gcc and wcslib are freely available under the GNU General Public Licence. Note that earlier versions of gcc or wcslib might work as well, but this has not been tested. In principle, other compilers that are compatible with gcc and support the C99 standard might also work, e.g. Apple’s clang compiler or the Intel C compiler, possibly with some minor tweaking of the installation script.

This version is used to create either a dynamic shared library _sofia.so (that can be called from Python) or a stand-alone binary sofia. The former allows data sources to be memory arrays, as opposed to the stand-alone binary, which reads in a FITS file.

A Makefile is provided to compile the code, with several options. Note that the 'OMP' parameter is optional and will enable multi-threading using OpenMP. If your compiler does not support OpenMP, this parameter can simply be omitted to install a single-threaded version of SoFiA 2.

Once all prerequisites are installed and available, simply enter the SoFiA 2 base directory and do one of the following (for more details on compile options, see the Makefile):

Ensure you have the dependency WCSLIB mentioned above, as well as SWIG installed (sudo apt install swig). You will also need numpy and in particular the numpy swig extensions:

pip3 install numpy

This will install numpy in your ~/.local/lib/python3/site-packages directory. For me, using pip did not install the swig extensions successfully, so I downloaded numpy-1.19.4, found the numpy.i and pyfragments.swg files (under tools/swig) and copied them across to my build directory.

"Python.h" is also required (python3-dev and libpython3-dev)

Now compile as follows:

1. "make clean"
2. "make shared OMP=true" (leave out OMP if you don't want OpenMP)

Read the comments in the example wrapper file "sofia_obj_wrapper.py" to see additional pre-requisites and how to run it.

Compile as follows:

1. "make clean"
2. "make exe OMP=true" (leave out OMP if you don't want OpenMP)

NOTE: Others may have created alternative ways of downloading and installing SoFiA 2. As we have no control over such third-party distributions, we cannot provide support for installation methods other than the ones described here. If you have installed SoFiA 2 through a third-party repository, please contact the administrator of that package in the case of installation issues.

An overview of all control parameters as well as a PDF copy of the SoFiA 2 User Manual can be found on the wiki at https://github.com/SoFiA-Admin/SoFiA-2/wiki. The wiki also contains a small test data cube and parameter file that users can download to verify their SoFiA 2 installation.

Several useful tools have been developed to help with running SoFiA 2 or process the output produced by the pipeline:

• SoFiA-X is a parallel wrapper around SoFiA 2 that can be used to process large data cubes in a supercomputing environment. Download: https://github.com/AusSRC/SoFiAX
• OptiFind is a wrapper around SoFiA 2 that can be used to search for HI emission in small regions of a data cube as defined by an input catalogue. Download: https://github.com/SoFiA-Admin/OptiFind
• SpecPlot is a tool for producing publication-ready plots of integrated spectra from SoFiA 2. Download: https://github.com/SoFiA-Admin/SpecPlot
• BusyFit is a tool for fitting the Busy Function to an integrated spectrum for the purpose of accurate parameterisation. Download: https://github.com/SoFiA-Admin/BusyFit

Users are requested to cite the following two papers in any work that is based on the use of SoFiA 2:

• SoFiA: a flexible source finder for 3D spectral line data
  Serra, P., Westmeier, T., Giese, N., et al., 2015, MNRAS, 448, 1922
  https://adsabs.harvard.edu/abs/2015MNRAS.448.1922S

• SoFiA 2 – An automated, parallel HI source finding pipeline for the WALLABY survey
  Westmeier, T., Kitaeff, S., Pallot, D., et al., 2021, MNRAS, in press
  https://adsabs.harvard.edu/abs/2021arXiv210615789W

Should you decide to run SoFiA 2 on your own data cubes, we would welcome any feedback on how well SoFiA 2 works for you and whether any improvements could be made. If you have a GitHub account, you can directly create a new issue (https://github.com/SoFiA-Admin/SoFiA-2/issues/new) on GitHub for questions, feature requests or bug reports. Alternatively, please feel free to directly contact the project leader, Tobias Westmeier, via e-mail at tobias.westmeier (at) uwa.edu.au to provide feedback on your experience with SoFiA 2. Note that the main purpose of SoFiA 2 is to facilitate the processing of HI data from SKA precursor surveys, and we are unlikely to be able to accommodate requests for additional features beyond this primary scope.

Copyright (C) 2021 Tobias Westmeier

SoFiA 2 is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.