Support - 5.2 English - 57404

AOCL User Guide (57404)

Document ID: 57404
Release Date: 2025-12-29
Version: 5.2 English

AOCL User Guide
Introduction
1. Introduction
1.1. Feature Support Matrix
Validation Matrix
2. Validation Matrix
Installing AOCL
3. Installing AOCL
3.1. Building from Source
3.1.1. Custom-Build Your AOCL Library
3.2. Installing AOCL Binary Packages
3.2.1. Using Master Package
3.2.2. Using Library Package
3.2.3. Using Debian and RPM Packages
Installing Debian Package
Uninstalling Debian Package
Installing RPM Package
Uninstalling RPM Package
Setting Environment Using Modules
Using Package Config
3.2.4. Using Windows Packages
Installing a Windows Package
Uninstalling a Windows Package
AOCL-BLAS
4. AOCL-BLAS
4.1. Installation
4.1.1. Requirements
4.1.2. Hardware Configuration
4.1.3. API Compatibility Layers (Calling AOCL-BLAS)
4.1.4. API Compatibility - Advanced Options
4.1.5. Other Key Options
4.1.6. Build AOCL-BLAS from Source on Linux
Single-Threaded AOCL-BLAS
Multi-Threaded AOCL-BLAS
4.1.7. Build AOCL-BLAS from Source on Windows
Building AOCL-BLAS Using GUI
Preparing Project with CMake GUI
Building the Project in Visual Studio GUI
Building AOCL-BLAS Using Command-Line Arguments
4.1.8. Using Pre-Built Binaries
4.2. Usage
4.2.1. Linking Application with AOCL-BLAS
4.2.2. AOCL-BLAS Usage in Fortran and C
Using BLAS API in Fortran
Using BLAS API in C
Using CBLAS API in C
Returning Complex Numbers
4.2.3. Dynamic Dispatch
Purpose
On Non-AMD “Zen” Architectures
Using Dynamic Dispatch
4.2.4. Fine Grained Code Selection
4.2.5. AOCL-BLAS Utility APIs
4.2.6. Managing AOCL-BLAS Memory in AOCL Applications
4.3. Testing and Benchmarking
4.3.1. Multi-Threaded AOCL-BLAS Test Suite Performance
4.3.2. Modifying the Test/Benchmark Test Sizes
4.4. Performance Tuning
4.4.1. AOCL-BLAS Thread Control
4.4.2. AOCL Dynamic
4.4.3. AOCL-BLAS Multi-Thread Tuning
4.4.4. Thread Count Considerations
4.4.5. Performance Suggestions for Skinny Matrices
4.5. Porting and Integration
4.6. Debugging and Troubleshooting
4.6.1. Error Handling in AOCL-BLAS
4.6.2. Debugging Build Using GDB
4.6.3. Viewing Logs of API calls
Enabling Call Logging and/or Tracing
Function Call Tracing
Debug Logging
Usage and Limitations
Updates in AOCL 5.2
4.6.4. Checking AOCL-BLAS Operation Progress
4.7. LPGEMM in AOCL-BLAS
4.7.1. Add-on in AOCL-BLAS
4.7.2. API Reference for GEMM with fused Post-Operations.
API Signature
4.7.3. API Reference for Batch GEMM with fused Post-Operations.
API Signature
4.7.4. API Reference for Element-wise Operations on Matrix (Without GEMM).
API Signature
4.7.5. Interface Reference for Post-Operations
Interface
Interface
Interface
Interface
Interface
Interface
Interface
Interface
Interface
Interface
Interface
Interface
4.7.6. API Reference for Matrix Reordering.
API Signature
API Signature
4.7.7. API Reference for Utility Operations.
API Signature
4.7.8. Enabling aocl_gemm Add-on
4.7.9. Sample Application 1
4.7.10. Sample Application 2
4.7.11. Sample Application 3
AOCL-Compression
5. AOCL-Compression
5.1. Installation
5.1.1. Requirements
5.1.2. Building from Source on Linux
5.1.3. Building from Source on Windows
5.1.4. Using Prebuilt Binaries
5.2. Testing and Benchmarking
5.2.1. Using Test suite
5.2.2. Performance benchmarking
5.3. Performance Tuning
5.3.1. Compile Time Tuning
5.3.2. Run Time Tuning
5.3.3. Reducing Run-to-Run Variation (Hardware Settings for Optimal Performance Benchmarking)
5.4. Porting and Integration
5.4.1. Introduction
Installed Package
APIs for Integration
5.4.2. Integration by Loading the Library at Runtime
Example - Integration with Postgres
Example - Integration with MariaDB
Example - Integration with GATK/Picard
Example - Integration with Kafka
Example - Integration with Cassandra
5.4.3. Integration by Linking to the Library at Compile Time
Example - Integration with Postgres
Example - Integration with MariaDB
5.4.4. Integration by Building from Source
Example - Integration with ClickHouse
5.4.5. Integration with benchmarking tools
Deflatebench
5.5. Appendix
5.5.1. Optional Build Parameters
5.5.2. Optional Runtime Parameters
Instruction Set Selection
5.5.3. Sample CMakeLists
5.5.4. Sample Makefile
AOCL-Cryptography Library
6. AOCL-Cryptography Library
6.1. Installation
6.1.1. Requirements
6.1.2. Building from Source on Linux
6.1.3. Building from Source on Windows
6.1.4. Using Prebuilt Binaries
6.2. Usage
6.3. Testing and Benchmarking
6.4. Performance Tuning
6.4.1. AOCL-Utils Integration
6.4.2. Choice of OpenSSL Version
6.4.3. GCM Performance Option
6.4.4. Runtime CPU Architecture Selection
6.5. Porting and Integration
6.5.1. Stack Representation for AOCL-Cryptography using Provider Integration
6.5.2. Hardware and Software Environment Tested
6.5.3. Configuring AOCL-Cryptography Provider With OpenSSL
6.5.4. Integration with Nginx
6.5.5. Performance Tools for SSL/TLS Configuration
6.6. Appendix
6.6.1. External Dependencies
AOCL-Data Analytics
7. AOCL-Data Analytics
7.1. Installation
7.1.1. Building from Git
Building from Source on Linux
Building from Source on Windows
CMake Build Options
7.2. Usage
7.2.1. Calling the C or C++ APIs
Calling the Library on Linux
Calling the Library on Windows
7.2.2. Calling the Python APIs
7.3. Performance Tuning
AOCL-DLP
8. AOCL-DLP
8.1. Library Overview
8.1.1. Components
8.1.2. Data Types
8.1.3. Call Layers
8.1.4. Hardware Features
8.2. Installation
8.2.1. Requirements
8.2.2. Building from Source on Linux
8.2.3. Building from Source on Windows
8.2.4. Using Prebuilt Binaries
8.3. Usage
8.3.1. On Linux
GEMM Operations
Post-Operations
Code Examples
8.3.2. On Windows
8.4. Testing and Benchmarking
8.4.1. Using Test Suite
8.4.2. Performance Benchmarking
8.5. Performance Tuning
8.5.1. Dynamic Dispatch
8.5.2. Multi-Threading
8.5.3. Runtime Thread Control
8.6. Porting and Integration
8.6.1. Integration Methods
8.6.2. Static vs Dynamic Linking
8.6.3. Integration Examples
8.6.4. Best Practices
8.7. Troubleshooting
8.7.1. Debugging
8.7.2. Error Handling
8.7.3. DTL Logging
8.7.4. Common Scenarios
8.8. Appendix
8.8.1. Licensing
8.8.2. Known Issues
8.8.3. External Dependencies
8.8.4. For More Information
AOCL-FFTW
9. AOCL-FFTW
9.1. Installation
9.1.1. Building from Source on Linux
9.1.2. Building from Source on Windows
Using CMake GUI to Build
Using Command-Line Arguments to Build
9.1.3. Using Pre-Built Libraries
9.2. Usage
9.2.1. Sample Programs for Single-Threaded and Multi-Threaded FFTW
9.2.2. Sample Programs for MPI FFTW
9.2.3. Additional Options
9.3. Performance Tuning
AOCL-FFTZ
10. AOCL-FFTZ
10.1. Installation
10.1.1. Requirements
10.1.2. Building on Linux
10.1.3. Building on Windows
Building with Visual Studio IDE (GUI)
Building with Visual Studio IDE (Command Line)
10.1.4. Additional Library Build Options
10.1.5. CPU Architecture Support and FMA Requirements
10.1.6. Testing and Benchmarking
Running Test Bench On Linux & Windows
Running tests with CTest
10.1.7. Running source code coverage using GCOV
10.1.8. Running Valgrind and ASAN memory checks using CTest
10.1.9. Generating Documentation
10.2. Usage
10.3. Constructing the Problem Descriptor
10.3.1. Structure Reference
10.3.2. Member-by-Member Guide
10.3.3. Validation Checklist
10.3.4. Common Pitfalls
10.3.5. Example: Minimal Valid Descriptor
10.4. Data Layout Conventions
10.4.1. Dimension Ordering
10.4.2. Input & Output Data Layout
10.4.3. Stride Setting
Row-Major Layout
Column-Major Layout
10.5. Performance Tuning
10.6. Porting and Integration
10.6.1. Support for Third-Party FFT libraries through Wrappers
10.6.2. Integration with AOCL-FFTZ
Integration by using FFTW APIs through Wrappers
Integration by Loading the Library at Runtime
Integration by Linking to the Library at Compile Time
Direct Integration using AOCL-FFTZ APIs
AOCL-LAPACK
11. AOCL-LAPACK
11.1. Installation
11.1.1. Requirements
11.1.2. Building from Source on Linux
11.1.3. Building from Source on Windows
Using CMake GUI
Using Visual Studio GUI
Using Command-Line Arguments
Configuring the Project
Building the Project
11.1.4. Using Pre-Built Libraries
11.2. Usage
11.2.1. On Linux
Using CMake
Using pkg-config
11.2.2. On Windows
11.3. Testing and Benchmarking
11.4. Performance Tuning
11.4.1. Enable AMD Optimizations
11.4.2. Enable / Disable Multithreading
11.4.3. Build-Time ISA Selection
11.4.4. Run-Time ISA Selection
11.4.5. Using AOCL-BLAS
11.4.6. Using Extended BLAS APIs
11.5. Checking Progress of AOCL-LAPACK Operations
11.6. Bit Reproducibility Testing (BRT)
11.6.1. Examples
AOCL-LibM
12. AOCL-LibM
12.1. Installation
12.1.1. Requirements
12.1.2. Building from Source
12.1.3. Building AOCL-LIBM on Linux and Windows using CMake
12.1.4. Building from Source on Linux using scons
12.1.5. Building from Source on Windows using scons
12.1.6. Using Prebuilt Binaries
12.2. Usage
12.2.1. On Linux
12.2.2. On Windows
12.3. Testing and Benchmarking
12.3.1. Using Test Suite
12.4. Performance Tuning
12.4.1. Dynamic Dispatch
12.5. Appendix
12.5.1. Licensing
12.5.2. Known Issues
AOCL-LibMem
13. AOCL-LibMem
13.1. Installation
13.1.1. Requirements
13.1.2. Building from Source on Linux
13.2. Usage
13.2.1. On Linux
13.2.2. Debug Build Configuration
13.3. Testing and Benchmarking
13.3.1. Using Test Suite
Debug Mode for LibMem Validator
Validator Script Method
CTest Utility Method
13.3.2. Performance Benchmarking
Report Description
Build and Compilers
Benchmark Framework Setup
Running Bench Framework
13.4. Performance Tuning
13.4.1. Dynamic Dispatch
13.4.2. Tunables
Running an Application with Tunables
13.4.3. Configuration Options
13.5. Troubleshooting
13.5.1. Debugging
13.5.2. Common Scenarios
AOCL-RNG
14. AOCL-RNG
14.1. Installation
14.1.1. Using Prebuilt Binaries
14.2. Usage
14.2.1. On Linux
14.2.2. On Windows
14.3. Performance Tuning
14.3.1. Dynamic Dispatch
14.3.2. Preferred Code Path
AOCL-ScaLAPACK
15. AOCL-ScaLAPACK
15.1. Installation
15.1.1. Requirements
15.1.2. Building from Source on Linux
15.1.3. Building from Source on Windows
Using CMake GUI
Using Visual Studio GUI
Using Command-Line Arguments
Configuring the Project
Building the Project
15.1.4. Using Prebuilt binaries
15.2. Testing
15.2.1. On Linux
Link using pkg-config
15.2.2. On Windows
15.3. Appendix
15.3.1. Checking AOCL-ScaLAPACK Operation Progress
15.3.2. Additional Features
AOCL-SecureRNG
16. AOCL-SecureRNG
16.1. Installation
16.1.1. Using Prebuilt Binaries
16.2. Usage
16.2.1. On Linux
16.2.2. On Windows
AOCL-Sparse
17. AOCL-Sparse
17.1. Installation
17.1.1. Requirements
17.1.2. Building from Source on Linux
17.1.3. Building from Source on Windows
Using CMake and Visual Studio GUI
Using Windows Command-Line
17.1.4. Using Prebuilt Binaries
17.2. Usage
17.2.1. On Linux
Link to Single-Threaded, LP64, Static Sparse Library
Link to Multi-Threaded, ILP64, Shared Sparse Library
17.2.2. On Windows
17.3. Testing and Benchmarking
17.3.1. Using Test Suite
17.3.2. Performance Benchmarking on Linux
17.3.3. Performance Benchmarking on Windows
17.4. Performance Tuning
AOCL-Utils
18. AOCL-Utils
18.1. Installation
18.1.1. Requirements
18.1.2. Building from Source on Linux
18.1.3. Building from Source on Windows
18.1.4. Using Prebuilt Binaries
18.2. Usage
18.2.1. On Linux
18.2.2. Examples
C API Example (cpuid Module)
C++ API Example (cpuid Module)
C API Example (Thread Pinning)
C++ API Example (Thread Pinning)
C API Example (Logger Module)
C++ API Example (Logger Module)
18.2.3. On Windows
18.3. Testing and Benchmarking
18.3.1. Using Test Suite
18.3.2. Performance Benchmarking
18.4. Performance Tuning
18.4.1. Build-Time Feature Selection
18.4.2. Application Optimization
18.4.3. Best Practices
18.5. Porting and Integration
18.6. Troubleshooting
18.6.1. Debugging
18.6.2. Error Handling
18.6.3. Logger Module Usage
18.6.4. Common Scenarios
18.7. Appendix
18.7.1. Licensing
18.7.2. Known Issues / Limitations
18.7.3. External Dependencies
18.7.4. For More Information
AOCL Build-It-Yourself
19. AOCL Build-It-Yourself
19.1. Working with AOCL Library Sources via Git Submodules
19.2. Configure Build-It-Yourself
19.2.1. Linux Prerequisites
19.2.2. Windows Prerequisites
19.2.3. Clone the Repository
19.2.4. Configure the Build Options
19.2.5. Build the Unified Binary
19.3. Examples of Configuration and Build Commands using CMake Presets
19.3.1. Introduction
19.3.2. On Linux
Single-Thread AOCL
Multi-Thread AOCL
19.3.3. On Windows
19.4. Verifying AOCL Installation
19.5. CMake Variables Reference
19.5.1. CMake Options to Select Libraries
19.5.2. CMake Options to Set Library Source Path
19.5.3. CMake Options to Set GIT Repository and Tag/Branch
Miscellaneous
20. Miscellaneous
20.1. OpenMPI
20.2. Unified Communication X (UCX)
20.3. OpenCV
Linking AOCL to Applications
21. Linking AOCL to Applications
21.1. High-Performance LINPACK Benchmark (HPL)
21.1.1. Configuring HPL.dat
21.1.2. Running the Benchmark
21.2. MUMPS Sparse Solver Library
21.2.1. Enabling AOCL with MUMPS
Using Spack on Linux
On Windows
Prerequisites
Prerequisites Checklist
CMake and Ninja
Intel OneAPI Toolkit
AMD AOCL Libraries
METIS Library
Boost Libraries
Build Instructions
Environment Setup
Build Methods
Build Options
Usage
Running the Test Executable
Troubleshooting
Common Issues
Getting Help
Important Notes
Project Structure
Support
22. Support
References
23. References
Appendix
24. Appendix
24.1. Check AMD Server Processor Architecture
24.1.1. On Linux
24.1.2. On Windows
24.2. Application Notes
24.2.1. AOCL-BLAS
24.2.2. AOCL-FFTW

Back to home page