{"id":13521081,"url":"https://github.com/AstroAccelerateOrg/astro-accelerate","last_synced_at":"2025-03-31T20:30:41.114Z","repository":{"id":7155977,"uuid":"8455118","full_name":"AstroAccelerateOrg/astro-accelerate","owner":"AstroAccelerateOrg","description":"AstroAccelerate is a many-core accelerated software package for processing time-domain radio-astronomy data.","archived":false,"fork":false,"pushed_at":"2025-01-21T09:47:00.000Z","size":5940,"stargazers_count":44,"open_issues_count":4,"forks_count":16,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-01-21T10:32:57.793Z","etag":null,"topics":["cuda","gpu","radio-astronomy"],"latest_commit_sha":null,"homepage":"https://www.oerc.ox.ac.uk/research-groups/astroaccelerate/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AstroAccelerateOrg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-02-27T12:04:06.000Z","updated_at":"2024-12-03T06:06:09.000Z","dependencies_parsed_at":"2024-06-04T19:22:16.817Z","dependency_job_id":"da058657-ab1b-45cb-8232-ef86259c836c","html_url":"https://github.com/AstroAccelerateOrg/astro-accelerate","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AstroAccelerateOrg%2Fastro-accelerate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AstroAccelerateOrg%2Fastro-accelerate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AstroAccelerateOrg%2Fastro-accelerate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AstroAccelerateOrg%2Fastro-accelerate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AstroAccelerateOrg","download_url":"https://codeload.github.com/AstroAccelerateOrg/astro-accelerate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246535758,"owners_count":20793316,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cuda","gpu","radio-astronomy"],"created_at":"2024-08-01T06:00:28.195Z","updated_at":"2025-03-31T20:30:40.202Z","avatar_url":"https://github.com/AstroAccelerateOrg.png","language":"C++","funding_links":[],"categories":["Single Pulse Search"],"sub_categories":[],"readme":"Repository for Astro-Accelerate Code\n====\n\nIntroduction\n===\nThis documentation summarises the content of the Astro-Accelerate software.\n\nPlease also refer to the [wiki pages](https://github.com/AstroAccelerateOrg/astro-accelerate/blob/master/wiki/home.md).\n\nPublications\n===\nIf you use AstroAccelerate, please cite the code using the following DOI and the relevant papers:\n* W. Armour, „AstroAccelerate\". Zenodo, lis. 20, 2020. doi: [10.5281/zenodo.4282748](https://doi.org/10.5281/zenodo.1212487).\n\nIf you use de-dispersion please also cite:\n* Novotný, J., Adámek, K., Clark, M. A., Giles, M., and Armour, W., “Accelerating Dedispersion Using Many-core Architectures”, *The Astrophysical Journal Supplement Series*, vol. 269, no. 1, IOP, 2023. doi:10.3847/1538-4365/acfef6. Accessible from: https://iopscience.iop.org/article/10.3847/1538-4365/acfef6.\n\nIf you use single-pulse detection please also cite:\n* Adámek, K. and Armour, W., “Single-pulse Detection Algorithms for Real-time Fast Radio Burst Searches Using GPUs”, *The Astrophysical Journal Supplement Series*, vol. 247, no. 2, IOP, 2020. doi:10.3847/1538-4365/ab7994. Accessible from: https://iopscience.iop.org/article/10.3847/1538-4365/ab7994\n\nIf you use Fourier domain acceleration search please also cite:\n* Dimoudi, S., Adamek, K., Thiagaraj, P., Ransom, S. M., Karastergiou, A., and Armour, W., “A GPU Implementation of the Correlation Technique for Real-time Fourier Domain Pulsar Acceleration Searches”, *The Astrophysical Journal Supplement Series*, vol. 239, no. 2, IOP, 2018. doi:10.3847/1538-4365/aabe88. Accessible from: https://iopscience.iop.org/article/10.3847/1538-4365/aabe88\n\nOther:\n* Armour, W., “A GPU-based Survey for Millisecond Radio Transients Using ARTEMIS”, in *Astronomical Data Analysis Software and Systems XXI*, 2012, vol. 461, p. 33. doi:10.48550/arXiv.1111.6399. Accessible from: https://aspbooks.org/custom/publications/paper/461-0033.html\n\nFeatures\n===\nAstro-Accelerate is used for real-time astronomy data processing. Its features include:\n* Acceleration Searching\n* Zero DM\n* RFI Mitigation\n\nPython Interface\n===\nAfter following the steps below, consider using the Python interface.\nAn example is provided in the `python/` folder.\nConfigurating pipelines using the Python interface is otherwise identical to an input_file (described below).\n\nSoftware Inputs and Outputs\n===\nThe software input is a sample data file.\nTo process the data file, astro-accelerate makes use of a configuration file.\nPlease see the section `Creating An Input Configuration File` for instructions on how to create a configuration file to process an input data file.\nThe software output is dependent on the choice of analysis component that is run.\n\nChecking the Configuration of the Graphics Processing Unit (GPU) and Support for CUDA\n\nIn a terminal window, type\n\n    nvidia-smi\n\nThe output will look similar to the following example\n```\n+-----------------------------------------------------------------------------+\n| NVIDIA-SMI 375.20                 Driver Version: 375.20                    |\n|-------------------------------+----------------------+----------------------+\n| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |\n| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |\n|===============================+======================+======================|\n|   0  Tesla P100-PCIE...  On   | 0000:02:00.0     Off |                    0 |\n| N/A   32C    P0    26W / 250W |      0MiB / 16308MiB |      0%      Default |\n+-------------------------------+----------------------+----------------------+\n|   1  Tesla P100-PCIE...  On   | 0000:03:00.0     Off |                    0 |\n| N/A   34C    P0    25W / 250W |      0MiB / 16308MiB |      0%      Default |\n+-------------------------------+----------------------+----------------------+\n                                                                              \n+-----------------------------------------------------------------------------+\n| Processes:                                                       GPU Memory |\n|  GPU       PID  Type  Process name                               Usage      |\n|=============================================================================|\n|  No running processes found                                                 |\n+-----------------------------------------------------------------------------+\n```\n\nIf no output is shown, or if an error appears, then it may indicate that a GPU has not been detected,\nor that the [CUDA toolkit](https://developer.nvidia.com/cuda-zone) is not properly installed.\n\nSelecting the Graphics Processing Unit (GPU) in the case of a system with more than one GPU\n===\nIf you have a multi-GPU system, you need can select the card by setting it in the input_file. The setting to add to the input_file is\n\n   selected_card_id X\n\nwhere `X` is a non-negative integer number which corresponds to the ID number of the GPU on your machine.\n\nSoftware Pre-Requisites\n===\nCUDA: CUDA 8.0 (see https://developer.nvidia.com/cuda-downloads)\n\nC/C++ (version): As supported and required by CUDA.\n\nCompiler: As supported by CUDA, but requiring also [OpenMP](https://www.openmp.org) support (compiler support can be found [here](https://www.openmp.org/resources/openmp-compilers-tools/)).\n\nCreating An Input Configuration File\n===\nAn example input configuration file is shown below:\n \n    range    0    150  0.1  1 1\n    range    150  300  0.2  1 1\n    range    300  500  0.25 1 1\n    range    500  900  0.4  2 2\n    range    900  1200 0.6  4 4\n    range    1200 1500 0.8  4 4\n    range    1500 2000 1.0  4 4\n    range    2000 3000 2.0  8 8\n    sigma_cutoff     6\n    analysis\n    -acceleration\n    -periodicity\n    -output_dmt\n    -zero_dm\n    -zero_dm_with_outliers\n    -rfi\n    fdas_custom_fft\n    -fdas_inbin\n    fdas_norm\n    debug\n    file /home/wa78/filterbank/ska-mid-b2.fil`\n \nFeatures can be turned on or off by adding a character at the beginning of the line (here \"-\" is used).\n\nSetting `range`\n=\n`range` tells the code to dedisperse and has input.\n\nThe format for the `range` parameter is\n`range dm_low dm_high dm_step downsampling_in_input_time downsampling_in_output_time`\nwhere `dm_low`, `dm_high`, `dm_step`, `downsampling_in_input_time`, and `downsampling_in_output_time` are to be replaced with suitable numerical values.\nFor example, a valid input for the `range` parameter is\n\n    range 500  900  0.4  2 2\n \nastro-accelerate will parse this input and dedisperse from a `dm` of `500` to a `dm` of `900` in steps of `0.4` (making (`900`-`500`)/`0.4` `dm` trials), with input data \ndownsampled in time by `2` (e.g. 64 uS would be binned into 128 uS samples).\n \nSetting `sigma_cutoff`\n=\n`sigma_cutoff` is the Signal-to-Noise Ratio (SNR) cutoff for your single pulse search.\n\nSetting `analysis`\n= \n`analysis` this tells the code to analyse the dedispersed data, outputting data into the output directory. The output data are binary files and so which can be read in gnuplot and python.\n\nFor example, you could use python as follows\n    splot \"./57663_22588_B0531+21_000007.fil/global_analysed_frb.dat\" binary format=\"%float%float%float%float\" u 1:2:3 palette\n \n Setting `acceleration`\n =\n`acceleration` this does a Fourier domain acceleration search on the data.\n\nSetting `periodicity`\n=\n`periodicity` sets a search for periodic objects.\n\nSetting `output_dmt`\n=\n`output_dmt` outputs the entire dedispersed data to a file (in ASCII).\n\nSetting `zero_dm`\n= \n`zero_dm` you can guess\n\nSetting `zero_dm_with_outliers`\n=\n`zero_dm_with_outliers` is part of the RFI mitigation routine.\n \nSetting `rfi`\n=\n`rfi` tries to eliminate RFI.\n(Astro-Accelerate welcomes developers to supply the team with data that includes RFI, which would be very helpful.)\n\nSetting `fdas_custom_fft`\n=\n`fdas_custom_fft` runs fourier domain acceleration search with a custom FFT.\n\nSetting `fdas_inbin`\n=\n`fdas_inbin` performs interbinning on the complex output.\n\nSetting `fdas_norm`\n=\n`fdas_norm` performs PRESTO block median normalization.\n\nSetting `debug`\n`debug` this gives detailed output.\n \nSetting `file`\nPlease supply the input data file by using the `file` setting followed by the path to a valid\ninput data file\n\n    file \u003cyour input file\u003e\n \nInput data files are by definition assumed to be formatted with 8-bit data.\nPlease contact Astro-Accelerate if you have input data that is not 8-bits let me know (development for support for this is in progress and we may be able to help).\n\nInstallation and Usage (Linux)\n===\nStep 1: Download the files\n==\nObtain the Astro-Accelerate code by doing\n    git clone https://github.com/AstroAccelerateOrg/astro-accelerate\n\nStep 2: Compile\n==\nEnsure you have the correct environment and pre-requisites.\nSet-up the environment (which will add CUDA to PATH and LD_LIBRARY_PATH)\n\n    source setup.sh\n\n`setup.sh` contains a hardcoded version number and a variable string to identify\nwhether the system is a 64-bit or 32-bit architecture. The user may need to edit\n`setup.sh` to suit the CUDA version number, library paths, and the architecture number\nin order to suit their needs. Users who already have all relevant CUDA paths configured\ndo not need to source setup.sh.\n\nAt this point, the user has a choice, they can either 1.) use the pre-configured Makefile\nthat comes with the repository by default, or they can 2.) configure the build system\nthemselves using CMake.\n\nNote that in the case of using CMake, the Makefile that CMake\nproduces will overwrite the default Makefile if the build is performed\nin source.\n\nTo run using the default Makefile, simply type\n\n    make\n\nTo configure the build system using CMake, create a `build` directory\n\n    mkdir build\n\nand then\n\n    cd build/\n\nrun CMake\n\n    cmake ../\n\nThe CUDA architecture can be specified with the `-DCUDA_ARCH` flag. For example, for architecture `7.0`, do\n\n    cmake -DCUDA_ARCH=\"7.0\" ../\n\nThe software can then be compiled using the generated Makefile. To do so, simply type\n\n    make\n\nIn both cases, the compilation process indicates which components are being compiled.\nThe result is an executable called\n\n    astro-accelerate\n\nin the directory from which the build was performed.\nIn the case of using the default Makefile,\nthe library is compiled as a static library called\n\n    libastroaccelerate.a\n    \nagainst which the executable is linked.\nIn the case of using CMake to configure the build system, the library is compiled\nas a shared object library called\n\n    libastroaccelerate.so\n\n\nagainst which the executable is linked.\nIn both cases, the library file will be located in the astro-accelerate build directory.\n\nThe user or developer may also with to run unit tests as part of the build. In this case, CMake should first be run with `-DENABLE_TESTS=ON` (the default is `OFF`) in order to enable the compilation of the tests, as follows\n\n    cmake -DCUDA_ARCH=\"7.0\" -DENABLE_TESTS=ON ../\n\nThe tests can then be run as follows\n\n    make test\n\nThe test results will be printed to the console.\nThe test executables are located in a separate folder in the build directory and are separate from the main standalone executable, they do not form a part of the compiled library or standalone astro-accelerate executable.\n\nStep 3: Run\n==\nAstro-Accelerate assumes its input is ready and compatible. To obtain compatible input, please follow the steps below. Please also ensure that the aforementioned environment variables have been set.\n\n1. Run astro-accelerate using the format\n\n        ./astro-accelerate /path/to/input_file.txt\n\nBy default, the output of astro-accelerate will be located in the same directory in which astro-accelerate was executed.\nConfiguration files may be used to further specify, set, and change options.\nBy default, the astro-accelerate executable looks for a configuration file in the same directory as the executable.\nA configuration file is required in order to run astro-accelerate.\nA number of example configuration files are included in the repository.\n\nStep 4: Results\n==\nTo print results from the `analysis` and `periodicity` modules using gnuplot, use the following command\n\n    splot \"../path/to/output_file.dat\" binary format=\"%f%f%f%f\" u 1:2:3 palette\n    \nwhich will plot the raw output data as saved to disk.\n\nOptimisations and Tuning\n==\nAstro-Accelerate comes with the facility to tune the software to the input that the user provides.\n1. To do this, `cd` to the `scripts` directory.\nModify `profiling.sh`, changing the line that says\n\n        ./astro-accelerate.sh ../input_files/ska_tune.txt\n\n    to\n\n        ./astro-accelerate.sh ../input_files/\u003cyour input file\u003e\n\n    where `\u003cyour input file\u003e` must be replaced by the input configuration file.\n\n3. The next step is to run the profiler tool that is provided in the repository\n\n        ./profiling.sh\n\n    This will create an optimised code for your search and GPU type.\n\n4. Then, astro-accelerate can be run as usual by doing \n\n        ./astro-accelerate.sh ../input_files/\u003cyour input file\u003e\n\n    where `\u003cyour input file\u003e` must be replaced by the path to the input configuration file as specified in the previous step.\n\nFurther Documentation\n===\nMore detailed information can be found on the [Wiki page of the repository](https://github.com/AstroAccelerateOrg/astro-accelerate/wiki) and the [Astro-Accelerate webpage](http://www.oerc.ox.ac.uk/projects/astroaccelerate).\n\nUsing Astro-Accelerate as a library\n===\nAstro-accelerate can be compiled and linked against as a library. A good demonstration of the user interface is provided in `main.cpp`. For more advanced use cases, a good example boilerplate code is provided in `aa_pipeline_generic.cpp`.\n\nThe user interface is centred around the user requesting a series of components that the library will compute as a pipeline. The ordering of the pipeline components is determined by the library, however the user may create a series of pipelines to create their own custom ordering.\n\nReturn types are provided as a `boolean` to indicate whether a method was successful or not. When a method in the pipeline configuration process returns `false`, the pipeline will not run, and the user should revisit their settings.\n\nWhen a method returns an object, then if the library cannot create a valid object, it will return an empty or trivial object. When an empty or trivial object is passed to the library at a later point, the relevant method will return `false`, or provide another empty or trivial object. Such a scenario prevents the astro-accelerate pipeline from running, in which case the user should revisit their settings. \n\nThe user can read `.fil` files or provide a `std::vector\u003cunsigned short\u003e` or a raw pointer of type `unsigned short`, but must in either case provide a valid `aa_filterbank_metadata` object that matches a filterbank data file (sigproc format).\n\n__User-side__\n* Select components (*__dedispersion__*, *__rfi__*, *__zero_dm__*, *__threshold__*,…).\n* Provide settings for the components (*__plan__*, *__strategy__*).\n* Run the pipeline (*__run__*).\n\n__Library-Side__\n* Astro accelerate decides on the *__strategy__* and the component ordering.\n* Data remain inside the pipeline until the end of the pipeline.\n* Validate the user settings beforehand.\n* All components adhere to the same programming idiom (*__plan__*, *__validate__*, *__strategy__*, *__validate__*, *__run__*).\n\nContact and Support\n===\nIf you notice any errors or have suggestions,\nplease contact someone on the astro-accelerate team,\nor file an issue or bug report on the repository.\n\nDisclaimers and Licensing\n===\nA number of code files may be covered by different licences.\nPlease refer to these seperately.\nPlease also refer to the Astro-Accelerate licence file provided.\n\nCopyright © 2018 Astro-Accelerate. All rights reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAstroAccelerateOrg%2Fastro-accelerate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAstroAccelerateOrg%2Fastro-accelerate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAstroAccelerateOrg%2Fastro-accelerate/lists"}