Add python api for cold warmup parameters

[oleksandr-pavlyk]

Closes #352

Adds Python API for methods added in #339:

• cuda.bench.Benchmark.set_cold_warmup_runs(count : SupportsInt)
• cuda.bench.Benchmark.set_cold_max_warmup_walltime(duration_seconds : SupportsFloat)
• cuda.bench.State.get_cold_warmup_runs()
• cuda.bench.State.set_cold_warmup_runs(count : SupportsInt)
• cuda.bench.State.get_cold_max_warmup_walltime()
• cuda.bench.State.set_cold_max_warmup_walltime(duration_seconds : SupportsFloat)

Also adds support for setting these through @cuda.bench.options.cold_warmup_runs(count) and @cuda.bench.options.cold_max_warmup_walltime(seconds).

N.B.: This PR is built on top changes from #347 and should be merged after it.

[oleksandr-pavlyk]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[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: cc6bbfc1-d831-4311-a78f-09a102502673

📥 Commits

Reviewing files that changed from the base of the PR and between d63a276 and 40220ed.

📒 Files selected for processing (5)

• python/cuda/bench/__init__.pyi
• python/cuda/bench/_decorators.py
• python/src/py_nvbench.cpp
• python/test/stubs.py
• python/test/test_cuda_bench.py

---

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Added cold warmup configuration (run count and max walltime) accessible via benchmark API, state, and option decorators.
• Tests
  • Added tests validating decorator application, registration order, state propagation, and runtime behavior for cold warmup options.
• Documentation
  • Updated docstrings to document new benchmark and state cold-warmup options.

suggestion:

Walkthrough

Adds cold-measurement warmup configuration: new Benchmark fluent setters and State getter/setters, bench.option decorators that apply those setters during registration, pybind11 bindings exposing the APIs to Python, and tests/examples validating behavior.

Changes

Cold warmup configuration API

Layer / File(s)	Summary
Python API type signatures python/cuda/bench/__init__.pyi	Benchmark gains set_cold_warmup_runs and set_cold_max_warmup_walltime; State gains get_/set_ pairs for both parameters; _OptionDecorators gains four decorator signatures (bare and set_ variants).
Decorator implementation python/cuda/bench/_decorators.py	Four option decorators append delayed actions that call the corresponding Benchmark.set_cold_warmup_runs / set_cold_max_warmup_walltime when the benchmark is registered.
C++ Python bindings python/src/py_nvbench.cpp	pybind11 bindings expose Benchmark::set_cold_warmup_runs, Benchmark::set_cold_max_warmup_walltime, and State getters/setters for cold warmup runs and max warmup walltime; class docstrings updated.
Tests and example stubs python/test/test_cuda_bench.py, python/test/stubs.py	Tests cover decorator application and docstrings, exercise State getters/setters and Benchmark setters in examples, and extend FakeBenchmark to record the new setter calls.

Assessment against linked issues

Objective	Addressed	Explanation
Add Python API to set warmup_runs [#352]	✅

Possibly related PRs

• NVIDIA/nvbench#347: Cold warmup decorator infrastructure extends the option decorator framework introduced in this PR.
• NVIDIA/nvbench#339: Python cold warmup methods and decorators mirror the C++ functionality added in this PR.

Suggested labels

type: enhancement

Suggested reviewers

• shwina
• NaderAlAwar

---

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

[coderabbitai]

🧹 Nitpick comments (1)

python/test/test_cuda_bench.py (1)

143-187: ⚡ Quick win

suggestion: Add one behavioral assertion path for bench.option.set_cold_warmup_runs(...) and bench.option.set_cold_max_warmup_walltime(...). The current test verifies only the alias decorators, so a regression in the set_ variants could pass unnoticed. As per coding guidelines, "python/**/*: Focus on Python API stability, pybind11/C++ exception boundaries, GIL behavior, CUDA interoperability, object lifetime, package metadata, type stubs, JSON/result parsing compatibility, and tests."

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 61b7c996-cd7c-48d0-9298-b31ec2122ee4

📥 Commits

Reviewing files that changed from the base of the PR and between d63a276 and aa2f782.

📒 Files selected for processing (5)

• python/cuda/bench/__init__.pyi
• python/cuda/bench/_decorators.py
• python/src/py_nvbench.cpp
• python/test/stubs.py
• python/test/test_cuda_bench.py

[oleksandr-pavlyk]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.