diff --git a/README.md b/README.md index 48c443131e7b58eceea01c1ee8586dfc129f7f11..1200e2c8cc9ba18577bba4260097899195bb61a1 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,113 @@ -# HPC_Imaging +# Radio Imaging Code Kernels -To compile the code, feel free to activate and deactivate options in the Makefile. -You will find the code options before and then the acceleration options. +Radio Imaging Code Kernels (RICK) is a software that is able to exploit parallelism and accelerators for radio astronomy imaging. **This software is currently under development**, feel free to contact us for issues, suggestions, information.
-You can simply run the code with the command: +RICK is written in C/C++ and can perform the following routines: +- gridding +- Fast Fourier Transform (FFT) +- w-correction -############################################ +It exploits the Message Passing Interface (MPI) and OpenMP for parallelism, and is able to run on both NVIDIA and AMD GPUs using CUDA, HIP, and OpenMP for GPU offloading. -make w-stacking +## Why and where to use RICK? -############################################ +Given that it is currently under development, RICK can be used to test its performances to your data. It has been tested for several radio interferometers: +- Low Frequency Array (LOFAR) +- Jansky Very Large Array (JVLA) +- Atacama Large Millimeter Array (ALMA) -It will redirect you to the file Build/Makefile.local, which is complete enough -apart from different library paths, feel free to use it or to change SYSTYPE. -My aim was to make compilation as simple as possible. +
-When you use GPU offloading with OpenMP, please do not compile the CPU part with NVC. -This can be easily fixed by setting the environment variable: +## What can RICK *not* do? -############################################ +Currently in RICK we have not yet implemented the following steps: -export OMPI_CC = gcc +- there is not the possibility to separate the Stokes parameters +- the flux scale is not physical +- the weighting step is currently under development -########################################### +
-In the case in which the default compiler is NVC. The Makefile is suited to understand -which are the parts to be compiled with NVC for the OpenMP offloading. -The final linker in this case will be however the NVC/NVC++. +## How to compile the code -The problem does not raise on AMD platforms, because you use clang/clang++ for both CPUs -and GPUs +The latest version of the code is in the *merge* branch. To compile it, you need first to specify in the Makefile the required configuration for the RICK execution.
+Here there is a brief explaination of each macro contained in the Makefile. +- USE_FFTW: enables the usage of the FFTW library with pure MPI +- HYBRID_FFTW: enables the usage of the hybrid FFT implementation with MPI+OpenMP using the FFTW library +- USE_OMP: to switch on OpenMP parallelization +- WRITE_DATA: write the full 3D cube of gridded visibilities and its FFT transform (impacts the performance, use only for debugging or tests) +- WRITE_IMAGE: write the final images as output +- PHASE_ON: performs w-stacking phase correction +- FITSIO: enables the usage of CFITSIO library to write outputs in FITS format +- PARALLELIO: enables the parallelization for final images writing (will be deprecated) +- NORMALIZE_UVW: normalize $u$, $v$, and $w$ in case it is not done in the binMS +- GAUSS: select a Gaussian gridding kernel +- GAUSS_HI_PRECISION: select an high-precision Gaussian gridding kernel +- KAISER_BESSEL: select a Kaiser-Bessel gridding kernel +- VERBOSE: enable verbose (impacts the performance, only for debugging or tests) +- NVIDIA: NVIDIA macro, required for NVIDIA calls +- CUDACC: enables CUDA for GPU offloading +- ACCOMP: enables OpenMP for GPU offloading +- GPU_STACKING: enables the w-stacking step on GPUs. This can be required because, at the moment, RICK cannot do on GPUs both the reduce and the w-stacking +- NCCL_REDUCE: use the NCCL implementation of the reduce on NVIDIA GPUs +- RCCL_REDUCE: use the accelerated implementation of the reduce on AMD GPU +- CUFFTMP: enables the distributed FFT on GPUs +- DEBUG: imacts hardly on the performance, to use only for development -The extensions of the executable will be changed depending on the different acceleration -options. +**Be careful because there are some macros that are obviously not compatible with others. More detailed instructions will be given to choose the best combination of macros for your usage or architecture.**
-To run the code, the data/paramfile.txt is available. Feel free to change the paramers, -i.e. the path of visibilities, which reduce implementation to use, the number of pixels, -the number of OpenMP threads and so on. +Once selected the desired macros, you need to select the architecture on which you want to execute the code. In the directory `Build/` there are several configuration files that adapt to your machine. To select your architecture you need to define the following environment variable +``` +> export $SYSTYPE=architecture_name +``` -Once you have compiled the code, run it simply with the command: +The latest version of RICK has been tested on the following architectures: +- Marconi 100 (CINECA) (`M100`) +- Leonardo (CINECA) (`leo`) +- MacOSX (`Macosx`) -########################################### +If your machine is not on the list, you can define `SYSTYPE=local` or modify it according to your needs and create one ad-hoc for your configuration.
-mpirun -np [n] [executable] data/paramfile.txt +When you use GPU offloading with OpenMP, please **do not compile the CPU part with NVC**. +This can be easily fixed by setting the environment variable: +``` +> export OMPI_CC = gcc +``` -########################################### +In the case in which the default compiler is NVC. The Makefile is suited to understand +which are the parts to be compiled with NVC for the OpenMP offloading. +The final linker in this case will be however the NVC/NVC++. + +The problem does not raise on AMD platforms, because you use clang/clang++ for both CPUs and GPUs. -In the case in which the code has been compiled without either -fopenmp or -D_OPENMP options, -the code is forced to use the standard MPI_Reduce implementation, since our reduce works -only with OpenMP. +At this point you can compile the code with the command: +``` +> make w-stacking +``` -To use the cufftMp with nvhpc 23.5 you have to add the following paths to the environmental variable ´LD_LIBRARY_PATH´: +An executable will be created whose name depends on the different implementations that have been required for the compilation. The extensions of the executable will be changed depending on the different acceleration options. +## How to execute the code -########################################### +To run the code, the `data/paramfile.txt` is available. Feel free to change the parameters according to your configuration and your desired output. Here we briefly list some of them: +- Datapath: path of the input Measurement Set +- num_threads: number of OpenMP threads +- reduce_method: select the type of reduce to be used for the execution. 0 corresponds to the MPI Reduce, 1 corresponds to the Reduce Ring +- grid_size_x, grid_size_y: size of the output image +- num_w_planes: number of w-planes for the w-stacking +- fftfile2, fftfile3: name of the output `.bin` real and imaginary files +- logfile: name of the log file -export LD_LIBRARY_PATH="/leonardo/prod/spack/03/install/0.19/linux-rhel8-icelake/gcc-11.3.0/nvhpc-23.5-pdmwq3k5perrhdqyrv2hspv4poqrb2dr/Linux_x86_64/23.5/comm_libs/11.8/nvshmem_cufftmp_compat/lib/:$LD_LIBRARY_PATH" -export LD_LIBRARY_PATH="/leonardo/prod/spack/03/install/0.19/linux-rhel8-icelake/gcc-11.3.0/nvhpc-23.5-pdmwq3k5perrhdqyrv2hspv4poqrb2dr/Linux_x86_64/23.5/math_libs/11.8/lib64/:$LD_LIBRARY_PATH" +In the case in which the code has been compiled without either -fopenmp or -D_OPENMP options, the code is forced to use the standard MPI_Reduce implementation, since our reduce works only with OpenMP. -########################################### \ No newline at end of file +To use the **cuFFTMp** with **nvhpc 23.5** you have to add the following paths to the environment variable `LD_LIBRARY_PATH`: +``` +> export LD_LIBRARY_PATH="/leonardo/prod/spack/03/install/0.19/linux-rhel8-icelake/gcc-11.3.0/nvhpc-23.5-pdmwq3k5perrhdqyrv2hspv4poqrb2dr/Linux_x86_64/23.5/comm_libs/11.8/nvshmem_cufftmp_compat/lib/:$LD_LIBRARY_PATH" + +> export LD_LIBRARY_PATH="/leonardo/prod/spack/03/install/0.19/linux-rhel8-icelake/gcc-11.3.0/nvhpc-23.5-pdmwq3k5perrhdqyrv2hspv4poqrb2dr/Linux_x86_64/23.5/math_libs/11.8/lib64/:$LD_LIBRARY_PATH" +``` + +Once you have compiled the code, run it simply with the command: +``` +> mpirun -np [n] [executable] data/paramfile.txt +```