Skip to content

v1.2.0
Compare
Choose a tag to compare
@dmed256 dmed256 released this 16 Sep 01:23
· 143 commits to main since this release
v1.2.0
1837907
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

Table of Contents

🔥 Exciting News

We introduce 3 awesome new features to the OCCA library. They are still in the 🃏 experimental stage, mainly due to performance reasons. We found an initial approach to enabling inlined lambdas and wanted to see how far we could go with them.

Future work includes profiling and optimizing build + launch of the inlined lambdas. How we cache kernel builds and fetch from the cache is still up in the air, but looking forward to tacking this fun problem 😃.

🃏 occa::forLoop and inlined kernels

Basic Example

Here we generate a for-loop that goes through [0, N) and tiled by tileSize

occa::forLoop()
  .tile({N, tileSize})
  .run(scope, OCCA_FUNCTION([=](const int index) -> void {
    // ...
  }));

We can do it manually by calling .outer and .inner

occa::forLoop()
  .outer(occa::range(0, N, tileSize))
  .inner(tileSize)
  .run(scope, OCCA_FUNCTION([=](const int outerIndex, const int innerIndex) -> void {
    const int index = innerIndex + (tileSize * innerIndex);
    // ...
  }));

Indices + Multiple Dimensions

We give an example where an index array is passed rather than a simple occa::range
Additionally, this @inner loop has 2 dimensions so the expected OCCA_FUNCTION should be taking in an int2 for the inner indices

occa::array<int> indices;
// ...
occa::forLoop()
  .outer(indices)
  .inner(X, Y)
  .run(scope, OCCA_FUNCTION([=](const int outerIndex, const int2 innerIndex) -> void {
    // ...
  }));

🃏 occa::array and Functional Programming

We introduce a simple wrapper on occa::memory which is typed and contains some of the core map and reduce functional methods.

Example

const double dynamicValue = 10;
const double compileTimeValue = 100;

occa::scope scope({
  // Passed as arguments
    {"dynamicValue", dynamicValue}
  }, {
  // Passed as compile-time #defines
    {"defines/compileTimeValue", compileTimeValue}
});

occa::array<double> doubleValues = (
  values.map(OCCA_FUNCTION(scope, [](int value) -> double {
    return compileTimeValue + (dynamicValue * value);
  }));
);

We also include a helper method occa::range which implements most of the occa::array methods but can be used without allocating data before iteration. It's useful if there is no specific input/output but still need to call a generic map or reduce function.

// Iterates through [0, 1, 2]
occa::range(3).map(...);

// Iterates through [3, 4, 5]
occa::range(3, 6).map(...);

// Iterates through [6, 5, 4]
occa::range(6, 3).map(...);

// Iterates through [0, 2, 4]
occa::range(0, 6, 2).map(...);

// Iterates through [6, 4, 2]
occa::range(6, 0, -2).map(...);

// No-op since there isn't anything to iterate through
occa::range(6, 0, 1).map(...);
Core methods
  • forEach
  • mapTo
  • map
  • reduce
Reduction
  • every
  • max
  • min
  • some
Re-indexing
  • reverse
  • shiftLeft
  • shiftRight
Utility methods
  • cast
  • clamp
  • clampMax
  • clampMin
  • concat
  • dot
  • fill
  • slice
Search
  • findIndex
  • find
  • includes
  • indexOf
  • lastIndexOf

🃏 Atomics

It's still in it's 🃏 experimental stage, but OKL now allows for basic atomic operations!

ℹ️   @atomic should be fully available for Serial and OpenMP modes. There is probably still room for improvement in the OpenMP implementation!

⚠️   GPU modes (HIP, CUDA, OpenCL) don't have general atomics implemented, only have the following basic updates:

  • @atomic value += update;
  • @atomic value -= update;
  • @atomic value &= update;
  • @atomic value |= update;
  • @atomic value ^= update;

Inlined @atomic

@atomic *ptr += value;

Block @atomic

If you prefer, you can use blocks which will be equivalent to inlined @atomic use if possible

@atomic {
  *ptr += value;
}

However, generic @atomic blocks are also possible

@atomic {
  *ptr  += value;
  *ptr2 += value2;
}

🃏 DPC++ Backend

The DPC++ backend was added by the great work completed jointly by ALCF and Intel, with contributions from:

  • Anoop Madhusoodhanan Prabha (Intel)
  • Cedric Andreolli (Intel)
  • Kris Rowe (ALCF)
  • Phillipe Thierry (Intel)
  • Saumil Patel (ALCF)

Notes

Currently only building with CMake is supported.

Code Transformation Rewrite

The way statement and expression code transformations are done have been fully rewritten!

A functional occa::lang::array class was introduced to help with statement (statement_t) and expression (exprNode) iteration and transformation. More information on PR #404.

Additionally the occa::lang::expr class helps create expressions easily without having to worry about pointers or underlying node objects. More information on PR #407.

⚠️ Breaking Changes

  • This is more of a potential breaking change but in a series of commits, we finally split up the public/private API!

  • occa::properties is now deprecated and replaced with occa::json

occa::properties wasn't adding much on top of occa::json, instead making auto-casting harder since we had to handle both json and prop objects. We still keep the properties and props naming convention throughout the library, since that's what they are but have transitioned the types to occa::json.

We still have a

typedef json properties;

so there shouldn't be any type-breaking changes for C++. The big difference is how std::string is being cast to json/properties:

  • std::string ? occa::properties: The std::string value is parsed into its JSON value. For example, we can pass {key: 1} or key: 1
  • std::string ? occa::json: The occa::json value is a literal string value. For example, if we pass {key: 1} then the occa::json value will be a string whose value is "{key: 1}".

Details about the refactor:
- [C++] The only breaking change is property strings now need to have the surrounding braces ({}) to make it valid JSON
- [C] All property methods have been removed and should be replaced with the Json methods
- [Fortran] All property methods have been removed and should be replaced with the Json methods

  • [#475 ] We're removing umalloc + UVA since it's only adding extra overhead and introduces a 3rd way to manage memory along with occa::memory and occa::array.

⭐ Features

  • [#376] Adds host: true option to malloc for better host-allocation strategies (Thanks @noelchalmers!)
  • [#404] Code transformation just got easier with the introduction of the very functional statementArray and exprNodeArray which makes it easy to:
    • Iterate through statements (forEach or nestedForEach (recursive))
    • Filter statements (filter or flatFilter (recursive))
    • Transform expressions (exprNode) through exprNodeArray::inplaceMap
  • [#407] Introduces the occa::lang::expr helper class to build expressions without having to know the underlying exprNode types or worry about pointers!
  • [#408] Adds okl/strict_headers kernel property to avoid erroring on headers OCCA can't find. Useful for mode-specific system headers.
  • [#409] Adds sourceCodeStatement to inject non-standard source code when needed.
  • [#410] Adds @atomic support (TODO: Finish most base implementations)
  • [#411] Updates bash autocomplete
  • [#420] Adds occa::setOccaCacheDir to programmatically set the OCCA_CACHE_DIR at runtime
  • [#421] Handle new HIP output formats in our builds (Thanks @dmcdougall!)
  • [#427] Adds occa::getDeviceCount (Thanks @noelchalmers!)
  • [#425] We now test CMake builds in our Github Actions (Thanks @noelchalmers!)
  • [#435] Adds device.wrapMemory to wrap native pointers into occa::memory objects
  • [#459] Adds occaKernelRunWithArgs which takes an occaType pointer
  • [#494] Adds DPC++ backend (Thanks @kris-rowe 🎉 🎉 🎉)
  • [#490] Changes how occa::memory tracks objects to properly handle slicing (Thanks @noelchalmers 🎉 )

🐛 Bugs Fixed

🎉 Contributors

Contributors

jedbrown, dmcdougall, and 4 other contributors
Assets 2
Loading