This repository provides pure Python implementation of uSARA, AIRI and cAIRI for small scale RI imaging problem which focuses on monochromatic intensity and a narrow filed of view.
uSARA[1,2] is the unconstrained counterpart of the SARA algorithm. It is underpinned by the forward-backward algorithmic structure for solving inverse imaging problem and uses a handcrafted sparsity-based image model.
AIRI[2] and its constraint variant cAIRI[3] are Plug-and-Play (PnP) algorithms used to solve the inverse imaging problem. By inserting carefully trained AIRI denoisers into the proximal splitting algorithms, one waives the computational complexity of optimisation algorithms induced by sophisticated image priors, and the sub-optimality of handcrafted priors compared to Deep Neural Networks.
The details of these algorithms are discussed in the following papers.
[1] Repetti, A., & Wiaux, Y., A forward-backward algorithm for reweighted procedures: Application to radio-astronomical imaging. IEEE ICASSP 2020, 1434-1438, 2020.
[2] Terris, M., Dabbech, A., Tang, C., & Wiaux, Y., Image reconstruction algorithms in radio interferometry: From handcrafted to learned regularization denoisers. MNRAS, 518(1), 604-622, 2023.
[3] Terris, M., Tang, C., Jackson, A., & Wiaux, Y., The AIRI plug-and-play algorithm for image reconstruction in radio-interferometry: variations and robustness, 2024, preprint arXiv:2312.07137v3.
We provide tutorials in the format of Jupyter notebook for both AIRI and uSARA as a quick start guide about how to run the scripts of this repository.
We also point the readers to AIRI and uSARA repositories for their MATLAB implementations.
This repository relies on two packages:
RI Measurement Operatorfor the python implementation of radio-interferometric measurement operator;PyTorch Wavelet Toolboxfor SARA wavelet dictionary.
These packages are associated with the following publication:
[4] Wolter, M., Blanke, F., Garcke, J., & Hoyt, C. T., ptwt-The PyTorch Wavelet Toolbox. JLMR, 25(80), 1-7. 2024.
To clone the project with the required submodules, you may consider one of the following set of instructions.
- Cloning the project using
https: you should run the following command
git clone --recurse-submodules https://github.com/basp-group/Small-scale-RI-imaging.git- Cloning the project using SSH key for GitHub: you should run the following command
git clone [email protected]:basp-group/Small-scale-RI-imaging.gitNext, edit the .gitmodules file, replacing the https addresses with the [email protected] counterpart as follows:
[submodule "src/ri_measurement_operator"]
path = src/ri_measurement_operator
url = [email protected]/basp-group/RI-measurement-operator.git
branch = pythonFinally, follow the instructions in the next session Updating submodules (optional) to clone the submodule into the repository's path.
The full path to this repository is referred to as $SSRI in the remainder of the documentation.
To update the submodules from your local $SSRI repository, run the following commands:
git pull
git submodule sync --recursive # update submodule address, in case the url has changed
git submodule update --init --recursive # update the content of the submodules
git submodule update --remote --merge # fetch and merge latest state of the submoduleIf you'd like to use our trained AIRI denoisers, you can find the ONNX files on Heriot-Watt Research Portal. You should download v1_airi_astro-based_oaid_shelf.zip and v1_airi_mri-based_mrid_shelf.zip, then copy the unzipped folders to $SSRI/airi_denoisers/ folder of this repository. Alternatively, make sure to update the full paths to the DNNs in the .csv file of the denoiser shelf.
We recommend to start by creating virtual environment with Python version higher than 3.11 using management tools such as conda or venv. Refer to PyTorch official website for the proper command to install the adequate PyTorch version. Finally, install other required packages using the following command:
pip install -r requirements.txtThe current code takes as input data a measurement file in .mat format containing the following fields:
"y" # vector; data (Stokes I)
"u" # vector; u coordinate (in units of the wavelength)
"v" # vector; v coordinate (in units of the wavelength)
"w" # vector; w coordinate (in units of the wavelength)
"nW" # vector; inverse of the noise standard deviation
"nWimag" # vector; square root of the imaging weights if available (Briggs or uniform), empty otherwise
"frequency" # scalar; observation frequency
"maxProjBaseline" # scalar; maximum projected baseline (in units of the wavelength; formally max(sqrt(u.^2+v.^2)))An example measurement file 3c353_meas_dt_1_seed_0.mat is provided in the folder $SSRI/data. The full synthetic test set used in [1] can be found in this (temporary) Dropbox link.
To extract the measurement file from Measurement Set Tables (MS), you can use the utility Python script $SSRI/ms2mat/ms2mat.py. Instructions are provided in the Readme File.
The configuration file is a .json format file comprising all parameters to run the different algorithms. A template file is provided in $SSRI/config/. An example example.json is provided in $SSRI/config/. A detailed description about the fields in the configuration file is provided here.
The algorithms can be launched through script run_imager.py. It uses the configuration file $SSRI/config/example.json.
python run_imager.pyIt also accepts 12 optional name-argument pairs which will overwrite corresponding fields in the configuration file.
python run_imager.py \
-c $PTH_CONFIG \ # path of the configuration file
--src_name $SRC_NAME \ # name of the target src used for output filenames
--data_file $DATA_FILE \ # path of the measurement file
--result_path $RESULT_PATH \ # path where the result folder will be created
--algorithm $ALGORITHM \ # algorithm that will be used for imaging
--im_dim_x $IM_DIM_X \ # horizontal number of pixels in the final reconstructed image
--im_dim_y $IM_DIM_Y \ # vertical number of pixels in the final reconstructed image
--dnn_shelf_path $DNN_SHELF_PATH \ # path of the denoiser shelf configuration file
--im_pixel_size $IM_PIXEL_SIZE \ # pixel size of the reconstructed image in the unit of arcsec
--superresolution $SUPERRE \ # used if pixel size not provided
--groundtruth $GROUNDTRUTH \ # path of the groundtruth image when available
--run_id $RUN_ID # identification number of the imaging run used for output filenamesDetailed instructions for how to launch uSARA and AIRI are provided in tutorial_airi_python.ipynb and tutorial_usara_python.ipynb. The scripts in these two Jupyter notebooks will reconstruct the groundtruth image $SSRI/data/3c353_gdth.fits from the measurement file $SSRI/data/3c353_meas_dt_1_seed_0.mat. The results will be saved in the folder $SSRI/results/.