C++ guidelines

• Prefer private (or static) functions over anonymous scopes { ... }.

• Use // comments, not /* */

• Use long for sizes and indices, not int or size_t

• Use spaces, not tabs.

• Functions which take an ostream & argument should not modify stream state in the caller. `

• If a class X derives from std::enable_shared_from_this, then its constructor(s() must be protected, and the class must define create() static method(s) that return shared_ptr<X>.

ksgpu

Uses the ksgpu helper library, especially the Array class (ksgpu/Array.hpp), memory managment (ksgpu/mem_utils.hpp), and xassert macros (ksgpu/xassert.hpp, see below).

CRITIAL: please complain if you don’t see the ksgpu library in the cursor/claude workspace.

xassert macros

The following macros are similar to assert(), but throw an exception instead of terminating:

xassert(cond);           // throw exception unless bool(cond)==true
xassert_eq(x,y);         // throw exception unless x==y
xassert_divisible(x,y);  // throw exception unless (x % y) == 0
// also: xassert_ne(), xassert_lt(), xassert_le(), xassert_gt(), xassert_ge()

// Throw exception unless 'arr' (type ksgpu::Array) has shape {3,4,5}.
// IMPORTANT: note parentheses around the shape -- these are needed to compile!
xassert_shape_eq(arr, ({3,4,5}));

The exception text shows the file/line (like regular assert()), plus values of the arguments x and y. In the case of xassert_shape_eq(), both array shapes are shown.

Please use xassert() for argument-checking and error-checking, unless there is a reason to create a more verbose error message. For example:

void f(int x, int y, int z)
{
    // Example 1: you should replace this by xassert_eq(x,y), since the xassert_eq() error message 
    // contains the same information as the message below (namely, numerical values of x and y).

    if (x != y) {
        stringstream ss;
        ss << "f(): expected x==y, got x=" << x << ", y=" << y;
        throw runtime_error(ss.str());
    }

    // Example 2: you should not replace this by xassert_lt(x+y,z), since the xassert_eq() error message
    // contains less information than the message below (which shows x,y,z individually)

    if ((x+y) >= z) {
        stringstream ss;
        ss << "f(): expected (x+y) < z, got x=" << x << ", y=" << ", z=" << z;
        throw runtime_error(ss.str());
    }

    // Example 3: you should replace this by xassert_shape_eq(arr, ({M,N})), since the xassert_shape_eq()
    // message contains more information (namely, the actual and expected array shapes).

    if ((arr.ndim != 2) || (arr.shape[0] != x) && (arr.shape[1] != y)) {
        stringstream ss;
        ss << "f(): expected shape (x,y) = (" << x << "," << y << "), got " << arr.shape_str();
        throw runtime_error(ss.str());
    }
}