[Upcoming] Version 1.2.0 Release Notes

[dmed256]

Table of Contents

• 🔥 Exciting News
  • 🃏 occa::forLoop and inlined kernels
  • 🃏 occa::array and Functional Programming
  • 🃏 Atomics
  • 🃏 DPC++ Backend
  • Code Transformation Rewrite
• ⚠️ Breaking Changes
• ⭐ Features
• 🐛 Bugs fixed
• 🎉 Contributors

🔥 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!

  • [973780b]
  • [1aeeb86]
  • [cb9a221]
  • [76ea695]

• 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

• [Removing umalloc on v1.2.0 (Feedback Wanted) #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

• [[Core] Adding hostMalloc API #376] Adds host: true option to malloc for better host-allocation strategies (Thanks @noelchalmers!)
• [[Lang] Add statementArray methods and switch over CUDA #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
• [[Lang][Expr] Adds expr: expression builder helper #407] Introduces the occa::lang::expr helper class to build expressions without having to know the underlying exprNode types or worry about pointers!
• [[Lang][Preprocessor] Adds okl/strict_headers option #408] Adds okl/strict_headers kernel property to avoid erroring on headers OCCA can't find. Useful for mode-specific system headers.
• [[Lang] Adds source code statement #409] Adds sourceCodeStatement to inject non-standard source code when needed.
• [[Lang] Adds @.atomic and a few implementations #410] Adds @atomic support (TODO: Finish most base implementations)
• [[CLI] Better autocomplete #411] Updates bash autocomplete
• [[QOL] Adds occa::env::setOccaCacheDir #420] Adds occa::setOccaCacheDir to programmatically set the OCCA_CACHE_DIR at runtime
• [Make build system understand new hipconfig output #421] Handle new HIP output formats in our builds (Thanks @dmcdougall!)
• [[Modes] Adding a getDeviceCount API to query number of available devices in an enabled mode #427] Adds occa::getDeviceCount (Thanks @noelchalmers!)
• [[CMake] Enable use of CMake in github actions .yml (continued from libocca/occa#342) #425] We now test CMake builds in our Github Actions (Thanks @noelchalmers!)
• [[Core] Adds wrapMemory #435] Adds device.wrapMemory to wrap native pointers into occa::memory objects
• [[C] Adds occaKernelRunWithArgs #459] Adds occaKernelRunWithArgs which takes an occaType pointer
• [[Modes] DPC++ backend #494] Adds DPC++ backend (Thanks @kris-rowe 🎉 🎉 🎉)
• [[Core][Modes] New buffer object to track underlying mode allocations … #490] Changes how occa::memory tracks objects to properly handle slicing (Thanks @noelchalmers 🎉 )

🐛 Bugs Fixed

• [[CMake] Fix intermittent errors when building Fortran examples/tests #405][[CLI] Report OCCA_MPI_ENABLED #412][[CMake] Fix changed subdirs in tests #413][[Fix] shadowing warnings #414] Lots of fixes from @SFrijters, thank you! 🎉
• [[#396] Avoids kernel calls on noop dim sizes #431] Avoid calling kernels when the run sizes are 0
• [[#399][Sys] Remove sysctl usage #432] Removed use of sysctl since it was deprecated and later removed from the C standard
• [[HIP] Update ptr ref hackery #437] Fix HIP pointer reference
• [Presumed race condition in caching #449] Replacing locks with temporary files to avoid race conditions (Thanks @SFrijters + @jedbrown!!)
• [[Lang] Adding missing if statement condition to inner statement array #456] Iterates through an if statement's condition (Thanks @noelchalmers!)
• [[Fortran] Generate fixed arity interface #477] Generate fixed arity interface (Thanks @SFrijters!)
• [Invalid reads in occa::primitive #495] Fixes unsafe use of strncmp (Thanks @MalachiTimothyPhillips!)

🎉 Contributors

• @dmcdougall
• @jedbrown
• @kris-rowe
• @MalachiTimothyPhillips
• @noelchalmers
• @SFrijters