# tensorplay.cuda.graphs API

Source: https://www.tensorplay.cn/docs/api/tensorplay.cuda.graphs.html

## Functions 5

[#](#api-tensorplay.cuda.graphs.export_dot)

### export_dot

function[Full reference ↗](/docs/generated/tensorplay.cuda.graphs.export_dot.html)

```python
tensorplay.cuda.graphs.export_dot(file_path: str) → str
```

Export the most recently completed capture to a DOT file.

Returns the path written.  For richer node attributes call
CUDAGraph.enable_debug_mode() before that capture.

[#](#api-tensorplay.cuda.graphs.graph_pool_handle)

### graph_pool_handle

function[Full reference ↗](/docs/generated/tensorplay.cuda.graphs.graph_pool_handle.html)

```python
tensorplay.cuda.graphs.graph_pool_handle()
```

Return an opaque token representing the id of a graph memory pool.

Pass it as the pool= argument of [graph()](/docs/generated/tensorplay.cuda.graphs.graph.html#tensorplay.cuda.graphs.graph) so several graphs
capture into (and reuse memory from) one shared private pool.

[#](#api-tensorplay.cuda.graphs.graph)

### graph

function[Full reference ↗](/docs/generated/tensorplay.cuda.graphs.graph.html)

```python
tensorplay.cuda.graphs.graph(cuda_graph, pool=None, stream=None, capture_error_mode='global')
```

Context-manager that captures CUDA work into a tensorplay.cuda.CUDAGraph.

Parameters:

- cuda_graph ([CUDAGraph](/docs/generated/tensorplay.cuda.graphs.CUDAGraph.html#tensorplay.cuda.graphs.CUDAGraph)) – the graph object to capture into.

- pool – None gives the graph its own private memory pool; an id from [graph_pool_handle()](/docs/generated/tensorplay.cuda.graphs.graph_pool_handle.html#tensorplay.cuda.graphs.graph_pool_handle) (or another graph / its pool_id property) shares that pool so allocations from both captures can recycle each other’s space.

- stream ([Stream](/docs/generated/tensorplay.cuda.streams.Stream.html#tensorplay.cuda.streams.Stream), optional) – custom capture stream; defaults to the runtime’s dedicated per-device side stream (the legacy default stream cannot capture).

- capture_error_mode ([str](https://docs.python.org/3/builtins/stdtypes.html#str), optional) – see [CUDAGraph.capture_begin()](/docs/generated/tensorplay.cuda.graphs.CUDAGraph.html#tensorplay.cuda.graphs.CUDAGraph.capture_begin).

[#](#api-tensorplay.cuda.graphs.is_current_stream_capturing)

### is_current_stream_capturing

function[Full reference ↗](/docs/generated/tensorplay.cuda.graphs.is_current_stream_capturing.html)

```python
tensorplay.cuda.graphs.is_current_stream_capturing()
```

Return True if CUDA graph capture is underway on the current thread.

[#](#api-tensorplay.cuda.graphs.make_graphed_callables)

### make_graphed_callables

function[Full reference ↗](/docs/generated/tensorplay.cuda.graphs.make_graphed_callables.html)

```python
tensorplay.cuda.graphs.make_graphed_callables(callables, sample_args, num_warmup_iters=3, allow_unused_input=False, pool=None, capture_error_mode='global')
```

Callables that run per-iteration with CUDA graph capture.

forward (and backward, via [tensorplay.autograd.grad()](/docs/generated/tensorplay.autograd.grad.html#tensorplay.autograd.grad)) into CUDA
graphs sharing one private memory pool, then wraps them in autograd
Functions whose forward/backward are graph replays.  Per-iteration host
overhead drops to two graph launches.

carried over verbatim: sample_args must contain only Tensors whose
requires_grad matches the live workload; modules may not carry hooks
or trainable buffers; arguments must keep their order and shapes.

Parameters:

- callables – function or tensorplay.nn.Module, or a tuple of them in live-workload order.

- sample_args – matching tuple of argument-tuples of CUDA Tensors.

- num_warmup_iters – warmup iterations run on the capture stream before capturing (flushes lazy cuDNN/cuBLAS state).

- allow_unused_input – passed through to [tensorplay.autograd.grad()](/docs/generated/tensorplay.autograd.grad.html#tensorplay.autograd.grad).

- pool – share an existing graph pool instead of allocating one.

## Classes 1

[#](#api-tensorplay.cuda.graphs.CUDAGraph)

### CUDAGraph

class[Full reference ↗](/docs/generated/tensorplay.cuda.graphs.CUDAGraph.html)

```python
class tensorplay.cuda.graphs.CUDAGraph
```

```python
begin_capture_to_if_node(scalar_pred)
```

Inside an open capture, gate the following work on an if node.

scalar_pred must be a single-element CUDA Bool tensor; at replay
time the driver samples it and runs the body captured between this
call and [end_capture_to_conditional_node()](#tensorplay.cuda.graphs.CUDAGraph.end_capture_to_conditional_node) only when true.

```python
begin_capture_to_while_node(scalar_pred)
```

Like [begin_capture_to_if_node()](#tensorplay.cuda.graphs.CUDAGraph.begin_capture_to_if_node), but the body loops while
the predicate stays true (driver-level while node).

```python
capture_begin(pool=None, capture_error_mode='global', stream=None)
```

Begin capture.

Parameters:

- pool – None captures into a fresh private pool; an id from [graph_pool_handle()](/docs/generated/tensorplay.cuda.graphs.graph_pool_handle.html#tensorplay.cuda.graphs.graph_pool_handle), another graph’s pool_id, or another [CUDAGraph](#tensorplay.cuda.graphs.CUDAGraph) shares that pool instead.

- capture_error_mode ([str](https://docs.python.org/3/builtins/stdtypes.html#str)) – "global" fails the capture if any unsafe CUDA call happens anywhere in the process; "thread_local" only watches this thread; "relaxed" does not guard against unsafe calls.

- stream – custom capture stream (a tensorplay.cuda.Stream). Defaults to the runtime’s dedicated per-device side stream; the legacy default stream cannot participate in capture.

```python
capture_end()
```

End capture and compile the executable (paid here, not on first
replay).

```python
debug_dump(path)
```

Write a DOT rendering of the captured graph to path.

Call enable_debug_mode() before capturing for a dump that
includes full node attributes.

```python
end_capture_to_conditional_node()
```

Close the open conditional body; subsequent capture returns to
the parent stream.

```python
instantiate()
```

No-op once instantiated; kept for late callers.

```python
property pool_id
```

Allocator pool id this graph captured against.

```python
replay(stream=None)
```

Run the graph: launch the cached executable on the current stream.

Parameters:

stream ([Stream](/docs/generated/tensorplay.cuda.streams.Stream.html#tensorplay.cuda.streams.Stream), optional) – launch on this explicit stream instead
of querying the current one - shaves a TLS lookup off hot
loops pinned to a single stream.

```python
reset()
```

Destroy the executable and release the pool reference.

All tensors allocated during the capture must be released first.

```python
set_conditional_handle_for_current_node(scalar_pred)
```

Refresh the predicate consumed by the innermost open conditional
node (used for nested conditionals).

```python
stage_and_launch(static_inputs, inputs)
```

Stage every input onto its static buffer and replay in one call.

Parameters:

- static_inputs – buffers captured by the graph (kept alive by the caller).

- inputs – fresh tensors whose contents overwrite the matching static buffer this iteration. Contiguous same-dtype/ same-device pairs take a raw async device-to-device copy; anything else falls back to full copy semantics.

This is the low-overhead bulk entry used by
tensorplay.compiler.backends.cudagraphs: one Python-to-native crossing
for the whole replay instead of one dispatcher round trip per input.