cuda.core.graph.GraphDefinition#

class cuda.core.graph.GraphDefinition#

A graph definition.

A GraphDefinition is used to construct a graph explicitly by adding nodes and specifying dependencies. Once construction is complete, call instantiate() to obtain an executable Graph.

Notes

Definitions that view the same root, child, or conditional graph hierarchy share underlying graph state. Mutations anywhere in that hierarchy must be externally synchronized.

Methods

__init__()#

Create a new empty graph definition.

allocate(
self,
size_t size,
*,
device: Device | int | None = None,
memory_type: GraphMemoryType = GraphMemoryType.DEVICE,
peer_access: list[Device | int] | None = None,
) → AllocNode#

Add an entry-point memory allocation node (no dependencies).

See GraphNode.allocate() for full documentation.

callback(
self,
fn: Callable[..., object],
*,
user_data: int | BufferProtocol | None = None,
) → HostCallbackNode#

Add an entry-point host callback node (no dependencies).

See GraphNode.callback() for full documentation.

clone(self) → GraphDefinition#

Create an independent copy of this graph definition.

Nodes, edges, parameters, and nested child graphs are copied. Resources referenced by nodes (buffers, kernels, events, and callbacks) are shared and independently retained; their contents are not copied. Subsequent graph mutations do not affect the other definition or its executables.

Returns:

An independently owned graph hierarchy. Use find_node() on the clone to obtain the counterparts of source nodes.

Return type:

GraphDefinition

Notes

CUDA rejects graphs containing memory allocation, memory free, or conditional nodes. Attached resources remain alive independently for each graph and are released at the appropriate lifetime boundary. Driver errors propagate as CUDAError. Serialize this call with all CUDA access to the underlying graph. See CUDA graph access.

create_condition(
self,
default_value: int | None = None,
) → GraphCondition#

Create a condition variable for use with conditional nodes.

The returned GraphCondition object is passed to conditional-node builder methods. Its value is controlled at runtime by device code via cudaGraphSetConditional.

Parameters:

default_value (int, optional) – The default value to assign to the condition. If None, no default is assigned.

Returns:

A condition variable for controlling conditional execution.

Return type:

GraphCondition

deallocate(self, dptr: int) → FreeNode#

Add an entry-point memory free node (no dependencies).

See GraphNode.deallocate() for full documentation.

debug_dot_print(
self,
path: str,
options: GraphDebugPrintOptions | None = None,
) → None#

Write a GraphViz DOT representation of the graph to a file.

Parameters:
  • path (str) – File path for the DOT output.

  • options (GraphDebugPrintOptions, optional) – Customizable options for the debug print.

edges(self) → set[tuple[GraphNode, GraphNode]]#

Return all edges in the graph as (from_node, to_node) pairs.

Returns:

Each element is a (from_node, to_node) pair representing a dependency edge in the graph.

Return type:

set of tuple

embed(
self,
GraphDefinition child: GraphDefinition,
) → ChildGraphNode#

Add an entry-point child graph node (no dependencies).

See GraphNode.embed() for full documentation.

empty(self) → EmptyNode#

Add an entry-point empty node (no dependencies).

Returns:

A new EmptyNode with no dependencies.

Return type:

EmptyNode

find_node(
self,
GraphNode original: GraphNode,
) → GraphNode#

Find a source node’s counterpart in this cloned graph.

Parameters:

original (GraphNode) – A valid node from the source graph that existed when this graph was cloned. The corresponding cloned node must still exist.

Returns:

The corresponding node, with its operation-specific subclass.

Return type:

GraphNode

Raises:
  • ValueError – If original is the synthetic entry node.

  • RuntimeError – If either graph definition is invalid or original was destroyed.

  • CUDAError – If CUDA cannot find a counterpart for a valid source node.

Notes

Lookup is local to this graph. Serialize this call with all CUDA access to either hierarchy. See CUDA graph access.

if_else(
self,
GraphCondition condition: GraphCondition,
) → IfElseNode#

Add an entry-point if-else conditional node (no dependencies).

See GraphNode.if_else() for full documentation.

if_then(
self,
GraphCondition condition: GraphCondition,
) → IfNode#

Add an entry-point if-conditional node (no dependencies).

See GraphNode.if_then() for full documentation.

instantiate(
self,
options: GraphCompleteOptions | None = None,
) → Graph#

Instantiate the graph definition into an executable Graph.

Parameters:

options (GraphCompleteOptions, optional) – Customizable dataclass for graph instantiation options.

Returns:

An executable graph that can be launched on a stream.

Return type:

Graph

join(self, *nodes: GraphNode) → EmptyNode#

Create an empty node that depends on all given nodes.

Parameters:

*nodes (GraphNode) – Nodes to merge.

Returns:

A new EmptyNode that depends on all input nodes.

Return type:

EmptyNode

launch(
self,
config: LaunchConfig,
kernel: Kernel,
*args,
) → KernelNode#

Add an entry-point kernel launch node (no dependencies).

See GraphNode.launch() for full documentation.

memcpy(
self,
dst: Buffer | int,
src: Buffer | int,
size_t size,
*,
dst_owner=None,
src_owner=None,
) → MemcpyNode#

Add an entry-point memcpy node (no dependencies).

See GraphNode.memcpy() for full documentation.

memset(
self,
dst: Buffer | int,
value,
size_t width,
size_t height=1,
size_t pitch=0,
*,
dst_owner=None,
) → MemsetNode#

Add an entry-point memset node (no dependencies).

See GraphNode.memset() for full documentation.

nodes(self) → set[GraphNode]#

Return all nodes in the graph.

Returns:

All nodes in the graph.

Return type:

set of GraphNode

record(self, event: Event) → EventRecordNode#

Add an entry-point event record node (no dependencies).

See GraphNode.record() for full documentation.

switch(
self,
GraphCondition condition: GraphCondition,
unsigned int count,
) → SwitchNode#

Add an entry-point switch conditional node (no dependencies).

See GraphNode.switch() for full documentation.

wait(self, event: Event) → EventWaitNode#

Add an entry-point event wait node (no dependencies).

See GraphNode.wait() for full documentation.

while_loop(
self,
GraphCondition condition: GraphCondition,
) → WhileNode#

Add an entry-point while-loop conditional node (no dependencies).

See GraphNode.while_loop() for full documentation.

Attributes