AstroAccelerate supported GPU status
| Compute Architecture | Architecture Name | Supported (Y/N) |
|---|---|---|
| 2.0 | Fermi | N |
| 2.1 | Fermi | N |
| 3.0 | Fermi | N |
| 3.2 | Kepler | N |
| 3.5 | Kepler | Y |
| 3.7 | Kepler | Y |
| 5.0 | Maxwell | Y |
| 5.2 | Maxwell | Y |
| 5.3 | Maxwell | Y |
| 6.0 | Pascal | Y |
| 6.1 | Pascal | Y |
| 6.2 | Pascal | - |
| 7.0 | Volta | Y |
AstroAccelerate supported CUDA® SDK status
| SDK Version | Supported (Y/N) |
|---|---|
| 8.0 | Y |
| 9.0 | Y |
| 10.0 | N |
AstroAccelerate supported build system versions
- AstroAccelerate can be compiled via
makeor viaCMake(> 2.6.0) which then generates a Makefile that can be used to create the shared object library and an executable which links against the library.
AstroAccelerate supported compilers
- The compiler for all device code is nvcc.
- For C++, the minimum recommended compiler is indicated on a per version basis. For more information, please see the NVIDIA CUDA Installation Guide.
AstroAccelerate supported operating systems
- In general, AstroAccelerate can be compiled on any system where the build system and compiler requirements are met. Only Linux distributions are officially supported at this time. Please see the NVIDIA CUDA Installation Guide for information about the operating system support for CUDA.
The code can be obtained from the astro-accelerate GitHub repository.
git clone git@github.com:AstroAccelerateOrg/astro-accelerate.git
Or
git clone https://github.com/AstroAccelerateOrg/astro-accelerate.git
Then go to into the code directory
cd astro-accelerate/
Please see the README.md in the top-level directory of the repository for further instructions on how to compile and run AstroAccelerate.
Please see the README.md in the top-level directory of the repository
for instructions on how to obtain, compile, and run AstroAccelerate.
In addition to being able to run as a standalone application, AstroAccelerate also offers an API, enabling it to be used in your own application code by linking against the AstroAccelerate shared object library object (.so) that is generated at compile-time.
The AstroAccelerate API offers the user the option to run a number of combinations of analysis components. The user is free to choose which components are to be run, but the API will validate that the combination is valid, and the API will determine the order in which those components are executed. The API executes the components as a pipeline. The user will therefore mostly interact with the aa_pipeline_api class, and may find it useful to refer to the Doxygen documentation for this class, in addition to the guidance provided here.
A pipeline is nothing more than a collection of components. There are also pipeline_options which consist of component_options which further specify how the components run. The components and component options are documented in aa_pipeline.hpp.
When a user first creates an aa_pipeline_api object, they must provide a pipeline which contain the components the user wishes to run. They must also provide the pipeline_option which contains the component options. In addition, the user must provide an aa_filterbank_metadata object, which contains the information about the time series data from a telescope (such as sampling rate, number of samples, and frequency binning information). Furthermore, a pointer to the raw input data must be provided (for a telescope .fil this can be obtained alongside the metadata by using the aa_sigproc_input class, but the user can also provide their own array data). Lastly, the user must configure a GPU card to run the pipeline on, using the aa_device_info class (which they can use to query the GPUs on the machine).
Once the aa_pipeline_api object is constructed, the user must still bind appropriate plan objects for each of the components they wish to run. There is one plan object for each component. For example, in order to run the analysis component, the user must bind an aa_analysis_plan. The plan contains the user's desired settings for how to run the component (such as the binning interval, and the dedispersion measure ranges to search for). In reality, user's settings may be sub-optimal from a performance perspective, so AstroAccelerate will optimise the user's plan by creating what is called a strategy. The strategy is created from the user's plan, and is the best compromise between the desired settings and good performance on the GPU. Strategy objects are required in order to run a pipeline, and the user is advised to verify and review the strategy when performing data analysis.
When binding the plan, the API bind call will return a boolean to indicate whether the bind was successful. The strategy can be obtained by calling a method by the component name and _strategy() added to it. For example, the periodicity_strategy() methods returns the currently calculated aa_periodicity_strategy based on the currently bound aa_periodicity_plan that the user provided.
All strategy objects have a ready state associated to them. All strategy objects must have a ready state set to true or else the API will not run the pipeline. The ready state of any strategy can be queried using the object's ready() method. Furthermore, the aa_pipeline_api's ready() method will check whether all plan objects were supplied and whether all strategy objects are ready.
The aa_pipeline_api offers a run() method, which will run the pipeline end-to-end.
There is a complete end-to-end example of using the API in include/aa_pipeline_generic.hpp.
There are also C-style wrapper functions (located in include/aa_pipeline_wrapper.hpp) for the include/aa_pipeline_generic.hpp code, which simplify the API interaction even further. An example is located in examples/src/filterbank_dedispersion.cpp.
Alternatively, a more advanced library user may wish to bypass the API, and interact directly with the pipeline classes that execute the components. This comes with more control (such as obtaining the pipeline output iteratively for each processed time chunk). However, this approach contains fewer safety checks than when using the API. The main differences are that the strategy objects are passed directly to the pipeline (bypassing the API), and the user must run the pipeline over all time chunks themselves. A good example code is located in examples/src/periodicity.cpp.
Boolean return values for functions return true for success or ready, whereas false indicates failure or not ready. It is advisable to check for errors at each step of configuring plan and strategy objects, and the API will help with this as well.
The inputs and outputs of the each of the components are tabulated below.
| Component | Description | Configuration objects | plan input / strategy input | Component output |
|---|---|---|---|---|
| dedispersion | Performs dedispersion of the input data. | aa_ddtr_plan / aa_ddtr_strategy | plan: dedispersion measure low, high, step, inBin, outBin, enable_msd_baseline_noise. strategy: aa_ddtr_plan, aa_filterbank_metadata, amount of gpu memory, flag to indicate if analysis will be used or not. |
dedispersed time chunk data (std::vector<unsigned short>) |
| analysis | Performs single pulse search (SPS) analysis of dedispersed data. | aa_analysis_plan / aa_analysis_strategy | plan: aa_ddtr_strategy, sigma_cutoff, sigma_constant, max_boxcar_width_in_sec, candidate_algorithm (flag), enable_msd_baseline_noise (flag). strategy: aa_analysis_plan. |
analysis_output struct (containing the data, dm_low, and dm_high for the time chunk) - see include/aa_device_analysis.hpp for further details. |
| periodicity | Performs a periodic peak finding analysis of dedispersed data. | aa_periodicity_plan / aa_periodicity_strategy | plan: sigma_cutoff, sigma_constant, nHarmonics, export_powers, candidate_algorithm (flag), enable_msd_baseline_noise (flag). strategy: aa_periodicity_plan. |
Output saved to disk in bespoke format. |
| fdas | Fourier Domain Accelerated Search of the dedispersed data. | aa_fdas_plan / aa_fdas_strategy | plan: sigma_cutoff, sigma_constant, num_boots, num_trial_bins, navdms, narrow, wide, nsearch, aggression, enable_msd_baseline_noise. strategy: aa_fdas_plan. |
Output saved to disk in bespoke format. |
Where more than one component takes an input by the same name, the standalone code will set the numerical values to be equal for all modules. The library user may, if they wish, configure this flag separately for all modules.
The default for output is to save to disk. If interacting directly with the pipeline, the user may call any one of the overloaded run methods on the pipeline (using flags to indicate whether the output will be dumped to disk and/or to the user at runtime), providing a std::vector to obtain dedispersed output from the dedispersion component, and an aa_analysis_output struct for the analysis single pulse search (SPS) output from the analysis component.
Users and developers alike may wish to use the logging facility provided by the aa_log class in order to log their activities to the console or to save it to a file on disk.
AstroAccelerate uses the logging class internally to provide output to the screen by default.
The logging facility provides several levels of logs. Please use it as described below.
| Level | Name | Use |
|---|---|---|
| Developer debug | log_level::dev_debug | Developer debugging information |
| User debug | log_level::debug | User debugging information |
| Notice | log_level::notice | Informational notices |
| Warning | log_level::warning | Behaviour that does not terminate execution. |
| Error | log_level::error | Behaviour that terminates execution. |
By default, the executable is compiled to include only log_level::notice messages or higher, so only notice, warning, and error are recorded. This behaviour can be changed at compilation by manually changing the LOG_THRESHOLD setting in aa_log.hpp to one of the named log_levels defined in the table above (default is log_level::notice). All logs of any kind can also be completely silenced at the build stage by providing CMake the -DLOGGING_FACILITY=OFF flag (default is ON).
To use logging in your code, include the logging class in your code
#include "aa_log.hpp"
Here are several examples of how to log a message
LOG(log_level::debug, "A user debug message");
LOG(log_level::notice, "A notice message");
LOG(log_level::warning, "A warning message");
LOG(log_level::error, "An error message");
By default, all messages are printed to the console. To save them to the disk instead, write:
FILE* pFile = fopen("/full/path/to/destination/logfile.log", "a");
FILElog::stream() = pFile;
All subsequent logs will then only be written to disk.
All logs will print the system date and time, the log level, and the log message.