occa: A C++ repository from yaomingamd

Performance, Portability, Transparency

OCCA is an open source, portable, and vendor neutral framework for parallel programming on heterogeneous platforms. The OCCA API provides unified models for heterogeneous programming concepts—such as a device, memory, or kernel—while the OCCA Kernel Language (OKL) enables the creation of portable device kernels using a directive-based extension to the C-language.

Mission critical computational science and engineering applications from the public and private sectors rely on OCCA. Notable users include the U.S. Department of Energy and Shell.

Key Features

Multiple backends—including CUDA, HIP, Data Parallel C++, OpenCL, OpenMP (CPU), and Metal
JIT compilation and caching of kernels
C, C++, and Fortran language support
Interoperability with backend API and kernels
Transparency—easy to understand how your code is mapped to each platform

Requirements

Minimum

CMake v3.17 or newer
C++17 compiler
C11 compiler

Optional

Fortan 90 compiler
CUDA 9 or later
HIP 3.5 or later
SYCL 2020 or later
OpenCL 2.0 or later
OpenMP 4.0 or later

Build, Test, Install

OCCA uses the CMake build system. Checkout the installation guide for a comprehensive overview of all build settings and instructions for building on Windows or Mac OS.

Linux

For convenience, the shell script configure-cmake.sh has been provided to drive the CMake build. Compilers, flags, and other build parameters can be adjusted there. By default, this script uses ./build and ./install for the build and install directories.

The following demonstrates a typical sequence of shell commands to build, test, and install occa:

$ ./configure.sh
$ cmake --build build --parallel <number-of-threads>
$ ctest --test-dir build --output-on-failure
$ cmake --install build --prefix install

If dependencies are installed in a non-standard location, set the corresponding environment variable to this path.

Use

Environment

During installation, the Env Modules file <install-prefix>/modulefiles/occa is generated. When this module is loaded, paths to the installed bin, lib, and include directories are appended to environment variables such as PATH and LD_LIBRARY_PATH.

Building an OCCA application

For convenience, OCCA provides CMake package files which are configured during installation. These package files define an imported target, OCCA::libocca, and look for all required dependencies.

For example, the CMakeLists.txt of downstream projects using OCCA would include

find_package(OCCA REQUIRED)

add_executable(downstream-app ...)
target_link_libraries(downstream-app PRIVATE OCCA::libocca)

add_library(downstream-lib ...)
target_link_libraries(downstream-lib PUBLIC OCCA::libocca)

Command-line Interface

The OCCA command-line interface can be found in <install-prefix>/bin/occa. This tool can be used to query information about hardware and the configuration of OCCA on a given platform.

For example, calling occa info will available OCCA backends and related hardware specs, while occa env display the values of OCCA related environment variables. To see the list of all available options, call occa --help.

$ occa info
========+======================+=================================
 CPU(s) | Processor Name       | AMD EPYC 7532 32-Core Processor 
        | Memory               | 251.6 GB                        
        | Clock Frequency      | 2.4 MHz                         
        | SIMD Instruction Set | SSE2                            
        | SIMD Width           | 128 bits                        
        | L1d Cache Size       |   1 MB                          
        | L1i Cache Size       |   1 MB                          
        | L2 Cache Size        |  16 MB                          
        | L3 Cache Size        | 256 MB                          
========+======================+=================================
 OpenCL | Platform 0           | NVIDIA CUDA                     
        |----------------------+---------------------------------
        | Device 0             | NVIDIA A100-PCIE-40GB           
        | Device Type          | gpu                             
        | Compute Cores        | 108                             
        | Global Memory        | 39.40 GB                        
========+======================+=================================
 CUDA   | Device Name          | NVIDIA A100-PCIE-40GB           
        | Device ID            | 0                               
        | Memory               | 39.40 GB                        
========+======================+=================================

Community

Support

Need help? Checkout the repository wiki or ask a question in the Q&A discussions category.

Feedback

To provide feedback, start a conversation in the general or ideas discussion categories.

Acknowledgements

This work was supported in part by

Argonne Leadership Computing Facility, which is a DOE Office of Science User Facility supported under Contract DE-AC02-06CH11357
The Exascale Computing Project (17-SC-20-SC), a joint project of the U.S. Department of Energy’s Office of Science and National Nuclear Security Administration, responsible for delivering a capable exascale ecosystem, including software, applications, and hardware technology, to support the nation’s exascale computing imperative
The Center for Efficient Exascale Discretizations (CEED), a co-design center within the U.S. Department of Energy Exascale Computing Project.
Intel
AMD
Shell

License

OCCA is available under a MIT license

yaomingamd/occa