Contribution Guidelines#

GLASS is a small, header-only CUDA library, and its value depends on every primitive being correct for any block size. These guidelines keep that invariant true. For the day-to-day developer workflow (build, test, benchmark) see Running Tests; for the deeper debugging runbook read docs/agent_debugging_guide.md in the repository.

Before you open a pull request#

  1. Add (or update) a test. Every public function needs a CUDA equivalence test in test/ that compares it against a NumPy/SciPy reference. See the existing test/test_l1.py / test_l2.py / test_l3.py.

  2. Sweep thread counts. A single-block kernel must produce identical results at 1 thread, 32 threads (one warp), a partial warp, and many warps. The most common GLASS bug is a missing __syncthreads() between a write phase and a later read — invisible at 32 threads, a race at 64+. Never test only at one warp.

  3. Test both storage orders where a function takes layout flags (ROW_MAJOR_* / TRANSPOSE_B).

  4. Run the suite: pytest test/ must be green (the harness compiles the CUDA sources once and caches by source hash).

  5. Document the public API. New public functions get a Doxygen /** */ block (@brief, @tparam, @param, NumPy equivalent) so they appear in the API Reference.

Coding conventions#

  • Public functions live under src/base/** (pulled into namespace glass by glass.cuh), with cooperative-groups variants in src/cgrps/** and vendor-backed variants in src/nvidia/**.

  • Keep primitives thread-count invariant: stride with for (i = rank; i < n; i += size) and place a __syncthreads() between any write phase and a dependent read.

  • Provide both runtime-sized and compile-time-sized (<T, N, ...>) overloads where it makes sense.

  • A formatting baseline lives in .clang-format (advisory — no enforced reformat pass).

Adding a new primitive — checklist#

  1. Implement it under the right src/ directory; add the #include to the relevant umbrella header (glass.cuh / glass-cgrps.cuh / glass-nvidia.cuh).

  2. Add a Doxygen doc-comment block.

  3. Add a CUDA test source under test/cuda/ and a pytest wrapper under test/ — and register any new source file in the compile-cache list in test/conftest.py so edits trigger a rebuild.

  4. Add an API-reference entry (a .. doxygenfile:: line) on the appropriate page under docs/source/api_reference/.

Documentation#

The docs build with Sphinx + Doxygen + Breathe. See Editing & Building the Docs for how to build and preview locally.