[STF] Add python bindings#5315
Conversation
|
/ok to test c9acb99 |
|
/ok to test 6971d8f |
|
/ok to test 2f7299e |
🟨 CI finished in 1h 40m: Pass: 91%/205 | Total: 1d 11h | Avg: 10m 28s | Max: 43m 15s | Hits: 96%/340562
|
| Project | |
|---|---|
| +/- | CCCL Infrastructure |
| CCCL Packaging | |
| libcu++ | |
| CUB | |
| Thrust | |
| CUDA Experimental | |
| stdpar | |
| python | |
| CCCL C Parallel Library | |
| Catch2Helper |
Modifications in project or dependencies?
| Project | |
|---|---|
| +/- | CCCL Infrastructure |
| +/- | CCCL Packaging |
| +/- | libcu++ |
| +/- | CUB |
| +/- | Thrust |
| +/- | CUDA Experimental |
| +/- | stdpar |
| +/- | python |
| +/- | CCCL C Parallel Library |
| +/- | Catch2Helper |
🏃 Runner counts (total jobs: 205)
| # | Runner |
|---|---|
| 128 | linux-amd64-cpu16 |
| 23 | windows-amd64-cpu16 |
| 14 | linux-amd64-gpu-h100-latest-1 |
| 14 | linux-amd64-gpu-rtxa6000-latest-1 |
| 12 | linux-arm64-cpu16 |
| 11 | linux-amd64-gpu-rtx2080-latest-1 |
| 3 | linux-amd64-gpu-rtx4090-latest-1 |
|
/ok to test fa8c960 |
🟨 CI finished in 1h 10m: Pass: 90%/205 | Total: 1d 13h | Avg: 10m 59s | Max: 39m 22s | Hits: 96%/340547
|
| Project | |
|---|---|
| +/- | CCCL Infrastructure |
| CCCL Packaging | |
| libcu++ | |
| CUB | |
| Thrust | |
| +/- | CUDA Experimental |
| stdpar | |
| python | |
| CCCL C Parallel Library | |
| Catch2Helper |
Modifications in project or dependencies?
| Project | |
|---|---|
| +/- | CCCL Infrastructure |
| +/- | CCCL Packaging |
| +/- | libcu++ |
| +/- | CUB |
| +/- | Thrust |
| +/- | CUDA Experimental |
| +/- | stdpar |
| +/- | python |
| +/- | CCCL C Parallel Library |
| +/- | Catch2Helper |
🏃 Runner counts (total jobs: 205)
| # | Runner |
|---|---|
| 128 | linux-amd64-cpu16 |
| 23 | windows-amd64-cpu16 |
| 14 | linux-amd64-gpu-h100-latest-1 |
| 14 | linux-amd64-gpu-rtxa6000-latest-1 |
| 12 | linux-arm64-cpu16 |
| 11 | linux-amd64-gpu-rtx2080-latest-1 |
| 3 | linux-amd64-gpu-rtx4090-latest-1 |
|
/ok to test f3b57da |
🟨 CI finished in 1h 05m: Pass: 89%/205 | Total: 1d 13h | Avg: 10m 53s | Max: 40m 23s | Hits: 95%/340359
|
| Project | |
|---|---|
| +/- | CCCL Infrastructure |
| CCCL Packaging | |
| libcu++ | |
| CUB | |
| Thrust | |
| +/- | CUDA Experimental |
| stdpar | |
| python | |
| CCCL C Parallel Library | |
| Catch2Helper |
Modifications in project or dependencies?
| Project | |
|---|---|
| +/- | CCCL Infrastructure |
| +/- | CCCL Packaging |
| +/- | libcu++ |
| +/- | CUB |
| +/- | Thrust |
| +/- | CUDA Experimental |
| +/- | stdpar |
| +/- | python |
| +/- | CCCL C Parallel Library |
| +/- | Catch2Helper |
🏃 Runner counts (total jobs: 205)
| # | Runner |
|---|---|
| 128 | linux-amd64-cpu16 |
| 23 | windows-amd64-cpu16 |
| 14 | linux-amd64-gpu-h100-latest-1 |
| 14 | linux-amd64-gpu-rtxa6000-latest-1 |
| 12 | linux-arm64-cpu16 |
| 11 | linux-amd64-gpu-rtx2080-latest-1 |
| 3 | linux-amd64-gpu-rtx4090-latest-1 |
|
/ok to test 4fb7000 |
🟨 CI finished in 1h 41m: Pass: 89%/205 | Total: 1d 12h | Avg: 10m 49s | Max: 45m 35s | Hits: 97%/340383
|
| Project | |
|---|---|
| +/- | CCCL Infrastructure |
| CCCL Packaging | |
| libcu++ | |
| CUB | |
| Thrust | |
| +/- | CUDA Experimental |
| stdpar | |
| python | |
| CCCL C Parallel Library | |
| Catch2Helper |
Modifications in project or dependencies?
| Project | |
|---|---|
| +/- | CCCL Infrastructure |
| +/- | CCCL Packaging |
| +/- | libcu++ |
| +/- | CUB |
| +/- | Thrust |
| +/- | CUDA Experimental |
| +/- | stdpar |
| +/- | python |
| +/- | CCCL C Parallel Library |
| +/- | Catch2Helper |
🏃 Runner counts (total jobs: 205)
| # | Runner |
|---|---|
| 128 | linux-amd64-cpu16 |
| 23 | windows-amd64-cpu16 |
| 14 | linux-amd64-gpu-h100-latest-1 |
| 14 | linux-amd64-gpu-rtxa6000-latest-1 |
| 12 | linux-arm64-cpu16 |
| 11 | linux-amd64-gpu-rtx2080-latest-1 |
| 3 | linux-amd64-gpu-rtx4090-latest-1 |
|
/ok to test 9acc75b |
| # define STF_WHILE_COND_MAX_TERMS 8 | ||
|
|
||
| //! \brief Combiner for multi-term while conditions. | ||
| typedef enum stf_cond_combiner |
There was a problem hiding this comment.
This could be extracted as as standalone PR (C combined conditions)
Mirror the fixes the regular logical_data path already had, which the stackable factory never received: - Require C-contiguous buffer-protocol exporters (PyBUF_C_CONTIGUOUS): the registered byte range is interpreted with the stored C-order shape, so a Fortran-ordered exporter was silently read in the wrong element order. - Keep the Py_buffer export alive until __dealloc__ instead of releasing it immediately: STF holds view.buf and may touch it asynchronously, and a resizable exporter (e.g. bytearray) could reallocate after release, leaving STF with a stale pointer. The held export also makes resize attempts fail loudly with BufferError. - Capture the source's readonly flag (CAI and buffer protocol), expose it as .readonly, and reject write()/rw() deps and write-capable push() modes on read-only sources. A read-only source is additionally auto-marked STF-level read-only: the stackable auto-import otherwise promotes even read accesses in nested scopes to an RW freeze, which triggers a pop/finalize write-back into memory the exporter declared immutable. set_read_only() now also raises the Python-side flag so misuse fails with a clear ValueError instead of a release-mode compiled-out C++ assertion. Add regression tests for all of the above across both context types, including the previously untested readonly-rejection path of the regular context. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Mirror pytorch_task: a failing t.end() in __enter__'s error path or in __exit__ while a body exception is propagating must not mask the original failure; only surface cleanup errors when the body succeeded. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
check_result defaulted to False, so the example harness (which calls main() with default arguments) only exercised control flow without ever validating the math. Check by default and replace the CLI --check flag with --no-check for benchmarking runs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
logical_data() previously rejected any CUDA Array Interface object that advertised a producer stream. Honor the CAI v3 contract instead: the consumer must order against the producer stream before touching the data, so synchronize the advertised stream once at registration (matching what Numba does on import). None means no synchronization, 1/2 map directly to the runtime's legacy/per-thread default stream handles, other values are raw cudaStream_t handles; 0 is rejected as the spec disallows it. An asynchronous producer-to-STF prerequisite (event wait instead of a host synchronization) can replace this later without an API change. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Point at the complete tested program in tests/stf/test_cuda_kernel.py so readers know where the undefined names (ctx, lX, kernel, ...) come from. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Same treatment as the cuda_kernel snippet: point at the complete tested program in tests/stf/interop/test_cuda_compute.py. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- test_from_context: importorskip("cupy") before device/green-context
setup so a missing cupy skips without allocating a green context.
- test_numba: drop dead return after pytest.skip().
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
😬 CI Workflow Results🟥 Finished in 2h 37m: Pass: 91%/528 | Total: 18d 13h | Max: 2h 36m | Hits: 36%/1869685See results here. |
|
@coderabbitai full review |
✅ Action performedFull review finished. |
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (4)
python/cuda_stf/tests/test_examples.py (1)
121-129: 🩺 Stability & Availability | 🔵 Trivial | 💤 Low valuesuggestion: add a
timeout=tosubprocess.runso a hanging example fails the test instead of stalling CI indefinitely.python/cuda_stf/tests/stf/examples/cg.py (1)
5-32: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valuesuggestion: docstring lists
host_launchunder "Demonstrates" (Line 12), but this example never callshost_launch. Drop that bullet to keep the teaching doc accurate.python/cuda_stf/tests/stf/examples/potri.py (1)
1033-1102: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick winsuggestion: the timed region (
start_timeat Line 1034 →end_timeat Line 1093) wraps thecheck_resultmatrix fills (host Python loops, Lines 1063-1075), thecompute_normhost tasks, andfinalize. Soelapsed_ms/GFLOPS is inflated by verification/setup work whencheck_result=True. Mirrorcholesky.py: bracket only the POTRI submission with adeviceSynchronize, and prefertime.perf_counter()overtime.time().python/cuda_stf/cuda/stf/_experimental/_stf_bindings_impl.pyx (1)
3279-3298: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valuesuggestion:
terms[8]and then > 8bound are hardcoded whileSTF_WHILE_COND_MAX_TERMSis declared as an extern C constant (and_combine_condat Line 3739 repeats the literal 8). If the C side ever changes the max, these silently diverge. Consider centralizing on the C constant.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: abc605ed-4698-4aff-ba70-c12f40e878eb
📒 Files selected for processing (83)
.github/CODEOWNERSAGENTS.mdc/experimental/stf/include/cccl/c/experimental/stf/stf.hc/experimental/stf/src/stf.cuc/experimental/stf/test/test_stackable.cuci/build_cuda_stf_combined_python.shci/build_cuda_stf_python.shci/build_cuda_stf_wheel.shci/matrix.yamlci/project_files_and_dependencies.yamlci/test/inspect_changes/c2h_dependency.outputci/test_cuda_stf_python.shci/util/workflow/get_wheel_artifact_name.shdocs/conf.pydocs/python/api_reference.rstdocs/python/index.rstdocs/python/setup.rstdocs/python/stf.rstdocs/python/stf_api.rstpython/cuda_stf/.gitignorepython/cuda_stf/CMakeLists.txtpython/cuda_stf/LICENSEpython/cuda_stf/README.mdpython/cuda_stf/cuda/stf/_experimental/__init__.pypython/cuda_stf/cuda/stf/_experimental/_cuda_version_utils.pypython/cuda_stf/cuda/stf/_experimental/_stf_bindings.pypython/cuda_stf/cuda/stf/_experimental/_stf_bindings_impl.pyxpython/cuda_stf/cuda/stf/_experimental/_stream_utils.pypython/cuda_stf/cuda/stf/_experimental/device_array.pypython/cuda_stf/cuda/stf/_experimental/fill_utils.pypython/cuda_stf/cuda/stf/_experimental/green_places.pypython/cuda_stf/cuda/stf/_experimental/interop/__init__.pypython/cuda_stf/cuda/stf/_experimental/interop/numba.pypython/cuda_stf/cuda/stf/_experimental/interop/pytorch.pypython/cuda_stf/cuda/stf/_experimental/paths.pypython/cuda_stf/cuda/stf/_experimental/task_graph.pypython/cuda_stf/merge_cuda_wheels.pypython/cuda_stf/pyproject.tomlpython/cuda_stf/tests/stf/examples/__init__.pypython/cuda_stf/tests/stf/examples/bicgstab.pypython/cuda_stf/tests/stf/examples/burger.pypython/cuda_stf/tests/stf/examples/burger_reference.pypython/cuda_stf/tests/stf/examples/cg.pypython/cuda_stf/tests/stf/examples/cholesky.pypython/cuda_stf/tests/stf/examples/fhe.pypython/cuda_stf/tests/stf/examples/fhe_decorator.pypython/cuda_stf/tests/stf/examples/neural_ode_dopri5.pypython/cuda_stf/tests/stf/examples/neural_ode_rk4.pypython/cuda_stf/tests/stf/examples/potri.pypython/cuda_stf/tests/stf/examples/stackable_branch_while_warp.pypython/cuda_stf/tests/stf/interop/__init__.pypython/cuda_stf/tests/stf/interop/test_cuda_compute.pypython/cuda_stf/tests/stf/interop/test_decorator.pypython/cuda_stf/tests/stf/interop/test_fdtd.pypython/cuda_stf/tests/stf/interop/test_jacobi_numba.pypython/cuda_stf/tests/stf/interop/test_jacobi_pytorch.pypython/cuda_stf/tests/stf/interop/test_jacobi_warp.pypython/cuda_stf/tests/stf/interop/test_legacy_to_stf.pypython/cuda_stf/tests/stf/interop/test_local_stf_capture.pypython/cuda_stf/tests/stf/interop/test_numba.pypython/cuda_stf/tests/stf/interop/test_pytorch.pypython/cuda_stf/tests/stf/interop/test_pytorch_task_context.pypython/cuda_stf/tests/stf/interop/test_scoped_capture.pypython/cuda_stf/tests/stf/interop/test_stencil_decorator.pypython/cuda_stf/tests/stf/interop/test_warp_pytorch_dag.pypython/cuda_stf/tests/stf/test_cai.pypython/cuda_stf/tests/stf/test_composite_places.pypython/cuda_stf/tests/stf/test_context.pypython/cuda_stf/tests/stf/test_cuda_kernel.pypython/cuda_stf/tests/stf/test_fill_utils.pypython/cuda_stf/tests/stf/test_from_context.pypython/cuda_stf/tests/stf/test_graph_scope.pypython/cuda_stf/tests/stf/test_host_launch.pypython/cuda_stf/tests/stf/test_launchable_graph.pypython/cuda_stf/tests/stf/test_lifecycle.pypython/cuda_stf/tests/stf/test_nested_scopes.pypython/cuda_stf/tests/stf/test_packaging.pypython/cuda_stf/tests/stf/test_place_support.pypython/cuda_stf/tests/stf/test_stream_utils.pypython/cuda_stf/tests/stf/test_task_graph.pypython/cuda_stf/tests/stf/test_token.pypython/cuda_stf/tests/stf/test_while_cond.pypython/cuda_stf/tests/test_examples.py
- cg.py: drop the host_launch docstring bullet, the example never calls it - potri.py: bracket only the POTRI submission with device synchronizes and time.perf_counter(), matching cholesky.py, so verification and finalize no longer inflate the reported GFLOPS - _stf_bindings_impl.pyx: use the STF_WHILE_COND_MAX_TERMS C constant instead of hardcoded 8s for while-condition term limits Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
If _get_stream_pointer raised on a malformed stream argument after the _PrimaryContextPin was acquired, context.__cinit__ aborted with _ctx still NULL, and since _PrimaryContextPin.__dealloc__ is a deliberate no-op the primary-context retains leaked until process exit. Resolve the stream pointer first so argument validation cannot strand the pin. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
@coderabbitai full review |
✅ Action performedFull review finished. |
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
ci/util/workflow/get_wheel_artifact_name.sh (1)
49-49: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winimportant: Missing
echoon line 49 causes an unhelpful "command not found" error instead of printing the job definition. Withset -eactive, the script exits before reachingexit 1on line 50.- "Job definition: $job_def" >&2 + echo "Job definition: $job_def" >&2
🧹 Nitpick comments (1)
python/cuda_stf/tests/test_examples.py (1)
92-95: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valuesuggestion:
hasattr(module, "__main__")/getattr(module, "__main__")is effectively dead — modules don't expose a__main__attribute, so only themainpath ever fires. Drop the__main__branch or replace it with the intended entry-point check.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 752e048a-cc2f-46da-9a8a-18ee3e5a3029
📒 Files selected for processing (80)
.github/CODEOWNERSAGENTS.mdci/build_cuda_stf_combined_python.shci/build_cuda_stf_python.shci/build_cuda_stf_wheel.shci/matrix.yamlci/project_files_and_dependencies.yamlci/test/inspect_changes/c2h_dependency.outputci/test_cuda_stf_python.shci/util/workflow/get_wheel_artifact_name.shdocs/conf.pydocs/python/api_reference.rstdocs/python/index.rstdocs/python/setup.rstdocs/python/stf.rstdocs/python/stf_api.rstpython/cuda_stf/.gitignorepython/cuda_stf/CMakeLists.txtpython/cuda_stf/LICENSEpython/cuda_stf/README.mdpython/cuda_stf/cuda/stf/_experimental/__init__.pypython/cuda_stf/cuda/stf/_experimental/_cuda_version_utils.pypython/cuda_stf/cuda/stf/_experimental/_stf_bindings.pypython/cuda_stf/cuda/stf/_experimental/_stf_bindings_impl.pyxpython/cuda_stf/cuda/stf/_experimental/_stream_utils.pypython/cuda_stf/cuda/stf/_experimental/device_array.pypython/cuda_stf/cuda/stf/_experimental/fill_utils.pypython/cuda_stf/cuda/stf/_experimental/green_places.pypython/cuda_stf/cuda/stf/_experimental/interop/__init__.pypython/cuda_stf/cuda/stf/_experimental/interop/numba.pypython/cuda_stf/cuda/stf/_experimental/interop/pytorch.pypython/cuda_stf/cuda/stf/_experimental/paths.pypython/cuda_stf/cuda/stf/_experimental/task_graph.pypython/cuda_stf/merge_cuda_wheels.pypython/cuda_stf/pyproject.tomlpython/cuda_stf/tests/stf/examples/__init__.pypython/cuda_stf/tests/stf/examples/bicgstab.pypython/cuda_stf/tests/stf/examples/burger.pypython/cuda_stf/tests/stf/examples/burger_reference.pypython/cuda_stf/tests/stf/examples/cg.pypython/cuda_stf/tests/stf/examples/cholesky.pypython/cuda_stf/tests/stf/examples/fhe.pypython/cuda_stf/tests/stf/examples/fhe_decorator.pypython/cuda_stf/tests/stf/examples/neural_ode_dopri5.pypython/cuda_stf/tests/stf/examples/neural_ode_rk4.pypython/cuda_stf/tests/stf/examples/potri.pypython/cuda_stf/tests/stf/examples/stackable_branch_while_warp.pypython/cuda_stf/tests/stf/interop/__init__.pypython/cuda_stf/tests/stf/interop/test_cuda_compute.pypython/cuda_stf/tests/stf/interop/test_decorator.pypython/cuda_stf/tests/stf/interop/test_fdtd.pypython/cuda_stf/tests/stf/interop/test_jacobi_numba.pypython/cuda_stf/tests/stf/interop/test_jacobi_pytorch.pypython/cuda_stf/tests/stf/interop/test_jacobi_warp.pypython/cuda_stf/tests/stf/interop/test_legacy_to_stf.pypython/cuda_stf/tests/stf/interop/test_local_stf_capture.pypython/cuda_stf/tests/stf/interop/test_numba.pypython/cuda_stf/tests/stf/interop/test_pytorch.pypython/cuda_stf/tests/stf/interop/test_pytorch_task_context.pypython/cuda_stf/tests/stf/interop/test_scoped_capture.pypython/cuda_stf/tests/stf/interop/test_stencil_decorator.pypython/cuda_stf/tests/stf/interop/test_warp_pytorch_dag.pypython/cuda_stf/tests/stf/test_cai.pypython/cuda_stf/tests/stf/test_composite_places.pypython/cuda_stf/tests/stf/test_context.pypython/cuda_stf/tests/stf/test_cuda_kernel.pypython/cuda_stf/tests/stf/test_fill_utils.pypython/cuda_stf/tests/stf/test_from_context.pypython/cuda_stf/tests/stf/test_graph_scope.pypython/cuda_stf/tests/stf/test_host_launch.pypython/cuda_stf/tests/stf/test_launchable_graph.pypython/cuda_stf/tests/stf/test_lifecycle.pypython/cuda_stf/tests/stf/test_nested_scopes.pypython/cuda_stf/tests/stf/test_packaging.pypython/cuda_stf/tests/stf/test_place_support.pypython/cuda_stf/tests/stf/test_stream_utils.pypython/cuda_stf/tests/stf/test_task_graph.pypython/cuda_stf/tests/stf/test_token.pypython/cuda_stf/tests/stf/test_while_cond.pypython/cuda_stf/tests/test_examples.py
| mkdir -p wheelhouse | ||
|
|
||
| # Clear stale STF wheels from a previous run so the per-CTK wheel selection | ||
| # below is unambiguous. Leave any co-located wheels (e.g. a cuda_cccl wheel | ||
| # staged by a combined producer job) untouched. | ||
| rm -f wheelhouse/cuda_stf-*.whl |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
important: remove stale wheelhouse_merged/ and wheelhouse_final/ before building. An interrupted prior run leaves repaired or merged wheels there; Lines 164-169 then glob and move them with the current result, potentially publishing stale artifacts. Keep the intentional dist/ lifecycle unchanged. As per path instructions, CI changes must handle cache and artifact state safely.
Sources: Path instructions, Learnings
| dependencies = [ | ||
| "numpy", | ||
| "cuda-pathfinder>=1.2.3", | ||
| "cuda-core", | ||
| "typing_extensions", |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Map repository layout and find the relevant docs/files first.
git ls-files | sed -n '1,200p'
printf '\n--- CONTRIBUTING / CI docs ---\n'
fd -a 'CONTRIBUTING.md|CI|ci|workflow' .
printf '\n--- cuda_stf package files ---\n'
fd -a 'pyproject.toml|green_places|cuda-core' python/cuda_stf .Repository: NVIDIA/cccl
Length of output: 20939
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Read the relevant documentation and package metadata in targeted slices.
for f in CONTRIBUTING.md .github/workflows/ci.yml python/cuda_stf/pyproject.toml; do
if [ -f "$f" ]; then
echo "===== $f ====="
wc -l "$f"
fi
done
echo "===== CONTRIBUTING.md (head) ====="
sed -n '1,220p' CONTRIBUTING.md
echo "===== CI workflow files ====="
fd -a '.github/workflows' . -t f | while read -r wf; do
echo "--- $wf ---"
sed -n '1,220p' "$wf"
done
echo "===== python/cuda_stf/pyproject.toml ====="
sed -n '1,220p' python/cuda_stf/pyproject.tomlRepository: NVIDIA/cccl
Length of output: 13079
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Search for green_places() definitions, docs, and any cuda-core version constraints.
rg -n "green_places\(|cuda-core|cuda_core|>= 1\.0|>=1\.0|1\.0" python/cuda_stf .github -g '!**/.git/**'Repository: NVIDIA/cccl
Length of output: 22677
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo '=== file inventory ==='
git ls-files | rg '^(CONTRIBUTING\.md|\.github/workflows/|python/cuda_stf/)'
echo
echo '=== CONTRIBUTING.md ==='
if [ -f CONTRIBUTING.md ]; then
sed -n '1,220p' CONTRIBUTING.md
fi
echo
echo '=== CI workflow files ==='
fd -a '.github/workflows' . -t f | while read -r wf; do
echo "--- $wf ---"
sed -n '1,220p' "$wf"
done
echo
echo '=== python/cuda_stf/pyproject.toml ==='
sed -n '1,220p' python/cuda_stf/pyproject.toml
echo
echo '=== search for green_places and cuda-core references ==='
rg -n "green_places\(|cuda-core|cuda_core|>= ?1\.0|>=1\.0" python/cuda_stf .githubRepository: NVIDIA/cccl
Length of output: 17463
🌐 Web query:
cuda-stf green_places cuda-core >= 1.0 documentation
💡 Result:
In the context of the CUDA Core Compute Libraries (CCCL), CUDASTF is a C++ library that implements a Sequential Task Flow (STF) model for CUDA [1][2]. The "green_places" you are inquiring about refers to the use of "green contexts" within the cuda::experimental::stf namespace, which provides SM-level partitioning of GPU resources [3]. Key documentation points include: 1. Green Contexts: Introduced in CUDA 12.4+, green contexts allow for partitioning GPU resources at the Streaming Multiprocessor (SM) level [3]. 2. Execution Places: In CUDASTF, an execution place defines where a task should run. exec_place_green_ctx is a specific execution place that designates tasks to run on a green context [4]. 3. Helper Classes: The green_context_helper class is provided to simplify the creation of green context views that can be utilized as execution places [5]. The green_ctx_view holds the underlying green context and its associated stream pool [6]. 4. Access: These features are part of the cuda::experimental::places namespace [3]. While they are integrated with CUDASTF, the places API can also be used as a standalone component [3]. Documentation for these features is available under the CUDA Core Compute Libraries (CCCL) documentation, specifically within the CUDA Experimental (CUDAX) section [3][1]. Regarding your mention of "cuda-core >= 1.0," note that CUDASTF is part of the experimental library (CUDAX) in the CCCL project and is distributed via the CCCL GitHub repository, rather than as part of the standard CUDA Toolkit [1].
Citations:
- 1: https://nvidia.github.io/cccl/unstable/cudax/stf.html
- 2: https://doi.org/10.1109/sc41406.2024.00049
- 3: https://nvidia.github.io/cccl/unstable/cudax/places.html
- 4: https://gevtushenko.github.io/cccl/cudax/api/classcuda_1_1experimental_1_1stf_1_1exec__place__green__ctx.html
- 5: https://gevtushenko.github.io/cccl/cudax/api/classcuda_1_1experimental_1_1stf_1_1green__context__helper.html
- 6: https://gevtushenko.github.io/cccl/cudax/api/classcuda_1_1experimental_1_1stf_1_1green__ctx__view.html
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo '=== python/cuda_stf/pyproject.toml dependency section ==='
sed -n '24,48p' python/cuda_stf/pyproject.toml
echo
echo '=== python/cuda_stf/cuda/stf/_experimental/green_places.py ==='
sed -n '1,220p' python/cuda_stf/cuda/stf/_experimental/green_places.py
echo
echo '=== python/cuda_stf/cuda/stf/_experimental/__init__.py ==='
sed -n '1,220p' python/cuda_stf/cuda/stf/_experimental/__init__.py
echo
echo '=== python/cuda_stf/README.md mentions ==='
rg -n "green_places|cuda-core|green context|green-context" python/cuda_stf/README.md python/cuda_stf/tests/stf/test_from_context.py python/cuda_stf/tests/stf/test_packaging.pyRepository: NVIDIA/cccl
Length of output: 11061
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
from pathlib import Path
p = Path("python/cuda_stf/pyproject.toml")
text = p.read_text()
for needle in ['"cuda-core"', 'green_places', 'cuda-core >= 1.0', 'cuda-core>=1.0']:
print(needle, text.find(needle))
PYRepository: NVIDIA/cccl
Length of output: 220
important: pin cuda-core>=1.0 in python/cuda_stf/pyproject.toml; green_places() is public and requires the green-context API, so the current unconstrained dependency can leave an older installed release in place until the feature fails at runtime.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
| # make an exception for the cudax test cmake file | ||
| cudax/test/CMakeLists.txt @nvidia/cccl-cudax-codeowners | ||
| # make an exception for STF test cmake files, following the PR #5406 cudax test precedent | ||
| # make an exception for STF test cmake files |
The Cython extension calls cudaStreamSynchronize directly (nogil CAI producer-stream sync) but links only the CUDA driver, so it relies on libcudart already being present in the process. Preload it through cuda.pathfinder alongside nvrtc and nvJitLink so a bare import works. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
cudaStreamSynchronize in _sync_cai_producer_stream was the extension's single CUDA runtime call, yet the module links only the CUDA driver, so imports relied on another package having already loaded cudart into the process. Call cuda.bindings.runtime instead (registration is not a hot path) and drop the RTLD_GLOBAL cudart preload workaround: the compiled bindings' symbol table is now honestly driver-only. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Description
Introduce Python bindings for CUDASTF as a new
cuda-stfpackage (modulecuda.stf._experimental, Linux only). The bindings sit on top of the STF C API (c/experimental/stf, already merged tomain) and expose contexts, logical data, tasks, execution/data places, CUDA graph utilities, and interop layers for Numba, PyTorch, Warp, andcuda.compute.Scope note for reviewers: the C API itself is not in this diff (it landed separately); execution-grid reshape bindings are split out into #9899. Of the ~21k added lines, ~13k are tests and examples — the reviewable core is ~5.9k lines of bindings + support code.
What's in the PR (per-area breakdown)
_stf_bindings_impl.pyx(4,270),_stf_bindings.pyloader,__init__.py, stream/version utilsdevice_array.py,task_graph.py,green_places.py,fill_utils.py,paths.py,interop/{numba,pytorch}.pyCMakeLists.txt,pyproject.toml,merge_cuda_wheels.py,README.mdci/build_cuda_stf_python.sh,ci/build_cuda_stf_wheel.sh,ci/test_cuda_stf_python.sh,ci/matrix.yamlhooksdocs/python/stf.rst(user guide),docs/python/stf_api.rst(API reference), setup docstests/stf/test_*.py— one file per feature areatests/stf/interop/— Numba, PyTorch, Warp, cuda.compute, legacy-stream interoptests/stf/examples/— CG, BiCGStab, Cholesky/POTRI, Burgers, neural ODEs, FHESuggested reading order
docs/python/stf.rst— the user-facing model; fastest way to understand what the API is supposed to feel like.python/cuda_stf/cuda/stf/_experimental/_stf_bindings_impl.pyx— the heart of the PR (walkthrough below).device_array.py,task_graph.py,interop/*) — thin layers over the bindings.cuda_ccclconventions.Walkthrough of
_stf_bindings_impl.pyxThe file is organized in layers, bottom-up (line anchors approximate):
dlopen-based loading oflibcccl.c.experimental.stf.so, ctypes structs for the data-place mapper callback (_MapperCallbackState,_make_mapper_callback), andAccessModeflags.stf_cai— the view type tasks hand back for deps._AliveFlag(guards use-after-finalize) and_PrimaryContextPin(keeps primary contexts alive while STF holds resources on them).logical_dataand deps (L781–L1072): the central data abstraction plusread/write/rwdep constructors.CudaStream, green-context views/helpers,exec_place,exec_place_grid,data_place. Grid places own arrays of handles; note the linear-order guarantees.task(acquire/release protocol, per-dep CAI export on the task stream) andcuda_kernel(kernel-launch task flavor).context(L2256–L2920): the main entry point — task creation,logical_datafactories, finalize semantics,async_resourcessharing.stackable_logical_data,stackable_task,LaunchableGraph+ graph scopes — CUDA-graph capture of STF sections.condexpressions,while_loop/repeatscopes, andstackable_contexttying it together.Key design points worth focused review:
cdef classwrapping a C handle uses explicit destroy-on-dealloc plus_AliveFlag; finalize order between Python GC and STF context shutdown is the trickiest part._sync_cai_producer_stream); task bodies run on the task's stream.Checklist