[STF] Support compound while-loop conditions in the C API

[caugonnet]

Description

Extracted from #5315 (see this review thread).

The built-in while-loop condition helper stf_stackable_while_cond_scalar() can only express a single comparison, so a loop guarded by, e.g., a convergence test and an iteration cap forces callers to allocate a synthetic condition scalar and schedule an extra task that combines the subconditions on the device.

This PR adds stf_stackable_while_cond_multi(): a single condition task that reads up to STF_WHILE_COND_MAX_TERMS (8) scalar logical data, evaluates each (*ld <op> threshold) term (with optional negation) and folds the results with an ALL (AND) or ANY (OR) combiner before updating the conditional handle:

stf_while_cond_term terms[2] = {
  {lres,  STF_CMP_GT, tol_sq,   STF_DTYPE_FLOAT64, 0},
  {liter, STF_CMP_LT, max_iter, STF_DTYPE_FLOAT64, 0},
};
stf_stackable_while_cond_multi(ctx, scope, terms, 2, STF_COND_ALL);

Implementation notes:

• The term pack is passed by value through kernel parameters (~200 bytes for 8 terms), so the condition kernel remains a single-thread launch with no device allocation, and stays CUDA-graph-capture friendly.
• Duplicate logical data across terms share one read dependency on the internal condition task.
• stf_stackable_while_cond_scalar() now delegates to the multi-term path, leaving a single condition kernel.

Motivation: Python compound while conditions

This entry point is the lowering target for the compound condition expressions of the Python STF bindings (#5315). Each flat &-chain or |-chain of comparisons maps 1:1 onto one stf_stackable_while_cond_multi() call, so e.g. a BiCGSTAB solver expresses its loop guard directly:

with ctx.while_loop() as loop:
    # ... solver step updating lres, a task incrementing liter ...
    loop.continue_while((lres > tol_sq) & (liter < max_iter))

instead of allocating a condition scalar and spending a dedicated task fusing the two tests on the device. The flat terms[] + combiner ABI keeps that lowering (and code generators targeting the C API directly) trivial while the kernel stays a single tiny launch regardless of the number of terms.

Testing

New C2H_TEST("stackable: while compound condition") in test_stackable.cu covering the ALL combiner with an iteration cap, the ANY combiner with a negated term, and duplicate-logical-data dependency sharing. Built with --preset cccl-c-stf and run on an RTX 3080 Ti (CUDA 13.0): all assertions pass.

Checklist

• New or existing tests cover these changes.
• The documentation is up to date with these changes (doxygen comments in stf.h).

🤖 Generated with Claude Code

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[caugonnet]

/ok to test b0cc738

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 21448054-5d66-4408-a379-f696224d305d

📥 Commits

Reviewing files that changed from the base of the PR and between 66218cc and 9bcd17d.

📒 Files selected for processing (1)

• c/experimental/stf/src/stf.cu

🚧 Files skipped from review as they are similar to previous changes (1)

• c/experimental/stf/src/stf.cu

---

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Added compound stackable while-loop conditions (up to 8 terms).
  • Combine term results using ALL or ANY semantics.
  • Each term supports its own comparison operator, data type, threshold, and optional negation.
  • Scalar while-loop conditions remain supported (now built on the compound capability).
• Bug Fixes
  • Correct dependency behavior when the same logical data is referenced across multiple condition terms.
• Tests
  • Added regression coverage for compound conditions, including ALL/ANY and negated terms.

Walkthrough

Changes

The stackable while-condition API now supports up to eight compound scalar terms with ALL/ANY combination, per-term comparison and negation, deduplicated dependencies, packed CUDA evaluation, scalar compatibility delegation, and regression tests.

Compound while condition

Layer / File(s)	Summary
Condition API contract c/experimental/stf/include/cccl/c/experimental/stf/stf.h	Defines the maximum term count, ALL/ANY combiner, term descriptor, and multi-term condition function.
Condition evaluation and scheduling c/experimental/stf/src/stf.cu	Packs and evaluates heterogeneous terms on the GPU, validates inputs, deduplicates logical-data dependencies, captures the task, and preserves scalar conditions through delegation.
Compound condition regression coverage c/experimental/stf/test/test_stackable.cu	Tests ALL and ANY conditions, negated terms, and duplicate logical-data handles with expected loop counts.

Suggested reviewers: bernhardmgruber

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

c/experimental/stf/src/stf.cu (2)

1587-1635: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

suggestion: cond_handle (1587) and stream (1635) are never reassigned; declare them const.

As per coding guidelines: "All variables that are not modified must be declared const, including cast results, function return values, and loop-invariant computations."

Source: Coding guidelines

---

1637-1650: 🩺 Stability & Availability | 🔵 Trivial | 💤 Low value

suggestion: mark cond_handle and stream const; they are never reassigned.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: a6743cc8-39f3-43d9-9df3-67872f61a0b7

📥 Commits

Reviewing files that changed from the base of the PR and between db2f947 and 66218cc.

📒 Files selected for processing (3)

• c/experimental/stf/include/cccl/c/experimental/stf/stf.h
• c/experimental/stf/src/stf.cu
• c/experimental/stf/test/test_stackable.cu

[caugonnet]

/ok to test 9bcd17d

[github-actions]

🥳 CI Workflow Results

🟩 Finished in 48m 45s: Pass: 100%/7 | Total: 1h 02m | Max: 48m 45s | Hits: 98%/786

See results here.