GXF App Python APIs#

Node#

class Node(ABC)#

Abstract base class for Graph, Entity, EntityGroup

abstract activate()#: Activate the node and its components.

abstract set_params()#: Set parameters for the node and its components.

Graph#

class Graph(Node)#

Python class wrapping the nvidia::gxf::Graph.

__init__(name: str = '')#

Initialize the Graph object.

Parameters:: name (str) – The name of the graph.

context: int#: The context associated with the graph. If the graph is a subgraph, returns the parent’s context.

name: str#: The name of the graph.

qualified_name: str#: The qualified name of the graph, including the parent’s name if the graph is a subgraph.

set_name(value)#

Set the name of the graph.

Parameters:: value (str) – The new name for the graph.

parent: Graph#: The parent graph, if the current graph is a subgraph.

set_parent(value)#

Set the parent graph, making the current graph a subgraph.

Parameters:: value (Graph) – The parent graph.

aliases: dict#: A dictionary of aliases for components in the graph.

update_alias(alias, value)#

Update the value of an alias.

Parameters:

alias (str) – The alias to update.
value – The new value for the alias.

Raises:

ValueError – If the alias is not set.

set_params()#: Set parameters for the graph.

get(alias)#

Get the value of an alias.

Parameters:: alias (str) – The alias to retrieve.
Returns:: The value associated with the alias.
Raises:: ValueError – If the alias is not marked visible.

make_visible(alias, component)#

Mark a component as visible with an alias.

Parameters:

alias (str) – The alias to associate with the component.
component – The component to make visible.

Raises:

RuntimeError – If the alias already exists.

is_subgraph: bool#: Whether the graph is a subgraph or not.

as_subgraph_of(parent)#

Make the current graph a subgraph of the given parent graph.

Parameters:: parent (Graph) – The parent graph.

activate()#: Activate the graph and its components.

add(node)#

Add a node (Entity, EntityGroup, or Graph) to the graph.

Parameters:: node (Entity, EntityGroup, or Graph) – The node to add.
Returns:: The added node.
Raises:: RuntimeError – If the node type is not supported.

load_extensions( extension_filenames=None, manifest_files=None, workspace='', )#

Load GXF extensions for the graph.

Uses env variable GXF_WORKSPACE as workspace

Generates extension_filenames based on the extensions used in the graph if no extension_filenames and manifest_files are passed

Parameters:

extension_filenames (list, optional) – List of extension library file paths (.so files)
manifest_files (list, optional) – List of manifest file paths.
workspace (str, optional) – Base directory for extensions and manifests.

set_severity(log_level=logging.INFO)#

Set the severity level for GXF logging.

Parameters:

log_level (optional, int or above enum from python logging package) –

The logging level to set. Can be one of the following:

logging.NOTSET (0): No logging.
logging.ERROR (40): Log only error messages.
logging.WARN (30): Log warning and error messages.
logging.INFO (20): Log informational, warning, and error messages.
logging.DEBUG (10): Log debug, informational, warning, and error messages.
"VERBOSE" (5): Log all messages, including verbose debug messages.

Raises:

RuntimeError – If an incorrect log level is provided.

run()#: Run the graph.

run_async()#: Run the graph asynchronously.

interrupt()#: Interrupt the graph.

wait()#: Wait for the graph to complete.

destroy()#: Destroy the graph and its context.

save(filename)#

Save the graph to a file.

Parameters:: filename (str) – The path to save the graph file.

Entity#

class Entity(Node)#

Entity class wrapping the nvidia::gxf::Entity.

__init__(name: str = '', is_system_entity: bool = False)#

Initialize the Entity object.

Parameters:

name (str) – The name of the entity.
is_system_entity (bool) – Whether the entity is a system entity or not.

context: int#: The context associated with the entity’s graph.

components: list#: A list of components associated with the entity.

named_components: dict#: A dictionary of named components associated with the entity.

eid: int#: The unique identifier of the entity.

set_graph(value)#

Set the graph associated with the entity.

Parameters:: value (Graph) – The graph.

name: str#: The name of the entity.

qualified_name: str#: The qualified name of the entity, including the graph’s name.

is_system_entity: bool#: Whether the entity is a system entity or not.

set_system_entity_flag(is_system_entity)#

Set the system entity flag for the entity.

Parameters:: is_system_entity (bool) – Whether the entity is a system entity or not.

activate()#: Activate the entity and its components.

set_params()#: Set parameters for the entity’s components.

add(component, visible_as=None)#

Add a component to the entity.

Parameters:

component (Component) – The component to add.
visible_as (str, optional) – An alias to make the component visible in the graph.

Returns:

The added component.

Raises:

Exception – If the input is not a Component object.

Component#

class Component#

Base class for components. Each component from different extensions inherits this class, and overrides:

gxf_native_type to its fully qualified C++ type name

_validation_info_parameters to its parameter info

gxf_native_type: str#: Base class variable to be override by the child fully qualified C++ type name.

_validation_info_parameters: dict#: Base class variable to be override by the child parameter info.

__init__(type, name, **params)#

Initialize the Component object.

Parameters:

type (str) – The type of the component.
name (str) – The name of the component.
params (dict) – The parameters for the component.

classmethod get_gxf_type()#

Get the native GXF type of the component.

Returns:: The native GXF type.
Return type:: str

name: str#: The name of the component.

type: str#: The type of the component.

entity: Entity#: The entity associated with the component.

params: dict#: The parameters of the component.

tid: int#: The type identifier of the component.

cid: int#: The unique identifier of the component.

context: int#: The context associated with the component’s entity.

add_to(entity)#

Add the component to an entity.

Parameters:: entity (Entity) – The entity to add the component to.

validate_params(params)#

Validate the component’s parameters.

Parameters:: params (dict) – The parameters to validate.
Returns:: True if the parameters are valid, False otherwise.
Return type:: bool

set_entity(entity)#

Set the entity associated with the component.

Parameters:: entity (Entity) – The entity to associate with the component.
Raises:: RuntimeError – If the component is already associated with an entity.

set_param(param, value)#

Set a parameter for the component.

Parameters:

param (str) – The parameter to set.
value – The value to set for the parameter.

Raises:

ValueError – If the parameter is not found.

get_param(param)#

Get the value of a parameter for the component.

Parameters:: param (str) – The parameter to get.
Returns:: The value of the parameter.
Raises:: ValueError – If the parameter is not found.

set_params()#: Set the parameters for the component.

EntityGroup#

class EntityGroup(Node)#

Entity group class wrapping the nvidia::gxf::Entity.

__init__(name: str = '')#

Initialize the EntityGroup object.

Parameters:: name (str) – The name of the entity group.

graph: Graph#: The graph associated with the entity group.

set_graph(value)#

Set the graph associated with the entity group.

Parameters:: value (Graph) – The graph.

context: int#: The context associated with the entity group’s graph.

name: str#: The name of the entity group.

qualified_name: str#: The qualified name of the entity group, including the graph’s name.

add(entities)#

Add entities to the group.

Parameters:: entities (Entity or iterable of Entities) – The entities to add.

activate()#: Activate the entity group and its entities.

set_params()#: Set parameters for the entity group.

ComputeEntity#

class ComputeEntity(Entity)#

Compute Entity adds an entity in the graph with basic scheduling terms. A codelet can be added to insert custom user code.

__init__(

self,

name: str = '',

count: int = -1,

recess_period: int = 0,

**kwargs,

)#

Initialize a ComputeEntity object.

If count >= 0, add CountSchedulingTerm with param count;

If recess_period > 0, add PeriodicSchedulingTerm with param recess_period;

Parameters:

name (str) – The name of the compute entity.
count (int) – The count parameter of PeriodicSchedulingTerm. A value of -1 indicates the entity can execute indefinitely.
recess_period (int) – The recess_period parameter of PeriodicSchedulingTerm. The duration in nanoseconds before the entity is permitted to execute.
**kwargs – Additional keyword arguments to be passed to the entity.

_recess_period: int#

_count: int#

_kwargs: dict#

add_codelet( self, codelet, min_message_available=1, min_message_reception=1, rx_capacity: int = 1, tx_capacity: int = 1, ) → Component#

Adds a codelet to the compute entity;

Automatically adds Transmitter queue DoubleBufferTransmitter and DownstreamReceptiveSchedulingTerm if the codelet parameter has nvidia::gxf::Transmitter;

Automatically adds Receiver queue DoubleBufferReceiver and MessageAvailableSchedulingTerm if the codelet parameter has nvidia::gxf::Receiver.

Parameters:

codelet (Component) – The codelet to be added to the compute entity.
min_message_available (int) – The minimum number of messages receiver queue received, only then permit codelet to execute. Skipped if codelet does not have receiver param.
min_message_reception (int) – The minimum number of messages transmitter queue can send to downstream, only then permit codelet to execute. Skipped if codelet does not have transmitter param.
rx_capacity (int) – The maximum number of messages allowed in the receiver queue. Skipped if codelet does not have receiver param.
tx_capacity (int) – The maximum number of messages allowed in the transmitter queue. Skipped if codelet does not have transmitter param.

Returns:

The added codelet.

Return type:

Component

PyComputeEntity#

class PyComputeEntity(Entity)#

Compute Entity to contain codelet implemented in python. It adds an entity in the graph with basic scheduling terms. A codelet implemented in python can be added.

__init__(

self,

name: str = '',

count: int = 100,

recess_period: int = 0,

**kwargs,

)#

Initialize a PyComputeEntity object.

If count >= 0, add CountSchedulingTerm with param count;

If recess_period > 0, add PeriodicSchedulingTerm with param recess_period;

Parameters:

name (str) – The name of the entity.
count (int) – The count parameter of PeriodicSchedulingTerm. A value of -1 indicates the entity can execute indefinitely.
recess_period (int) – The recess_period parameter of PeriodicSchedulingTerm. The duration in nanoseconds before the entity is permitted to execute.
**kwargs – Additional keyword arguments to be passed to the entity.

_recess_period: int#

_count: int#

_kwargs: dict#

add_codelet(

self,

name,

codelet,

min_message_available=1,

min_message_reception=1,

rx_capacity: int = 1,

tx_capacity: int = 1,

**params,

) → Component#

Adds a codelet implemented in python to the python compute entity;

Automatically adds Transmitter queue DoubleBufferTransmitter and DownstreamReceptiveSchedulingTerm if the codelet parameter has nvidia::gxf::Transmitter;

Automatically adds Receiver queue DoubleBufferReceiver and MessageAvailableSchedulingTerm if the codelet parameter has nvidia::gxf::Receiver.

Parameters:

name (str) – The name of the python codelet.
codelet (Component) – The python codelet to be added to the compute entity.
min_message_available (int) – The minimum number of messages receiver queue received, only then permit codelet to execute. Skipped if codelet does not have receiver param.
min_message_reception (int) – The minimum number of messages transmitter queue can send to downstream, only then permit codelet to execute. Skipped if codelet does not have transmitter param.
rx_capacity (int) – The maximum number of messages allowed in the receiver queue. Skipped if codelet does not have receiver param.
tx_capacity (int) – The maximum number of messages allowed in the transmitter queue. Skipped if codelet does not have transmitter param.

Returns:

The added python codelet.

Return type:

Component

standard_methods#

connect(src: Component, target: Component, graph: Graph = None)#

Module:: gxf.std.standard_methods

Connects two queue components within a graph.

Parameters:

src (Component) – The source queue component.
src – The target queue component.
graph (Graph) – The graph that has above two components.

enable_job_statistics(

g: Graph,

name: str = '__job_stats',

**kwargs,

) → Component#

Module:: gxf.std.standard_methods

Add a JobStatistics to a graph.

Parameters:

g (Graph) – The graph to enable job statistics.
name (str) – The name of JobStatistics.
**kwargs – Additional keyword arguments to be passed to the JobStatistics.

Returns:

The added JobStatistics.

Return type:

Component

set_scheduler(g: Graph, sch: Component) → Component#

Module:: gxf.std.standard_methods

Set a Scheduler component to the graph.

Parameters:

g (Graph) – The graph to set Scheduler.
sch (Component) – The Scheduler to set to the graph.

Returns:

The added Scheduler.

Return type:

Component

set_clock(g: Graph, clock: Component) → Component#

Module:: gxf.std.standard_methods

Set a clock component to the graph, so that the components need a clock in the graph can use that clock.

Parameters:

g (Graph) – The graph to set clock.
clock (Component) – The clock to set to the graph.

Returns:

The added clock.

Return type:

Component

GXF_NAME_EXTRA_LENGTH = 7

Module:: gxf.std.standard_methods

_generate_name(base_name, extra_length=GXF_NAME_EXTRA_LENGTH)#

Module:: gxf.std.standard_methods

Generate a random name with base_name as prefix, {base_name}_*.

Parameters:

base_name (str) – The name prefix.
extra_length (int) – The length of postfix.

Returns:

The generate random name.

Return type:

str

class Tensor#

The Tensor class represents a multi-dimensional array of elements of the same data type.

Protocols implemented: * DLPack * array_interface and cuda_array_interface

__init__()#: Construct a new empty Tensor.

static as_tensor(obj)#

Parameters:: obj (object) – The input object to be converted to GXF Tensor.
Returns:: A new Tensor instance initialized with the data from the input object, zero-copy.
Return type:: Tensor

Create a new GXF Tensor instances from various other deep leanring frameworks, with data zero-copy if the tensor object support the DLPack protocol, NumPy’s array interface protocol, or the CUDA array interface protocol.

Example:

>>> import numpy as np
>>> arr = np.random.rand(3, 4)
>>> from gxf.std import Tensor
>>> tensor = Tensor.as_tensor(arr)

static from_dlpack(obj)#

Parameters:: obj (object) – An object supporting the DLPack protocol.
Returns:: A new Tensor instance initialized with the data from the input DLPack object, zero-copy.
Return type:: Tensor

Create a new Tensor instance from an object supporting the DLPack protocol.

Example:

>>> import numpy as np
>>> arr = np.random.rand(3, 4)
>>> from gxf.std import Tensor
>>> tensor = Tensor.from_dlpack(arr)

__dlpack__(stream=None)#

Parameters:: stream (object) – An optional stream object wrapping cuda stream for the DLPack protocol.
Returns:: A PyCapsule object wrapping DLPack representation of the Tensor.

__dlpack_device__()#

Returns:: A PyCapsule object wrapping DLPack device representation of the Tensor.

get_tensor_info()#

Returns:: A tuple containing information about the Tensor (pointer, size, data type, rank, dimensions, and strides).

Get detailed information about the Tensor in a tuple format.

shape()#

Returns:: The shape of the Tensor.
Return type:: Shape

Get the shape of the Tensor.

element_type()#

Returns:: The element data type of the Tensor.
Return type:: PrimitiveType

Get the element data type of the Tensor.

storage_type()#

Returns:: The storage type of the Tensor (kHost or kDevice or kSystem).
Return type:: MemoryStorageType

Get the storage type of the Tensor.

reshape(tensor_description, allocator)#

Parameters:

tensor_description (gxf.std.TensorDescription) – A TensorDescription object describing the new shape and data type.
allocator (Allocator) – An Allocator instance for memory allocation.

Reshape the Tensor according to the provided TensorDescription.

reshape_custom( shape, element_type, bytes_per_element, strides, storage_type, allocator, )#

Parameters:

shape (gxf.std.Shape) – The new shape for the Tensor.
element_type (gxf.std.PrimitiveType) – The new element data type for the Tensor.
bytes_per_element (int) – The number of bytes per element in the new data type.
strides (list[int]) – The strides for the new shape.
storage_type (gxf.std.MemoryStorageType) – The new storage type for the Tensor (host or device).
allocator (Allocator) – An Allocator instance for memory allocation.

Reshape the Tensor with custom parameters.

get_tensor_description()#

Returns:: A TensorDescription object describing the current Tensor.
Return type:: gxf.std.TensorDescription

Get a TensorDescription object describing the current Tensor.

static add_to_entity(entity, tensor=None, name=None)#

Parameters:

entity – The Entity to which the Tensor should be added.
tensor (Tensor, optional) – An optional Tensor instance to be added to the Entity. If not provided, a new empty Tensor will be created.
name (str, optional) – An optional name for the Tensor component in the Entity.

Returns:

The Tensor instance added to the Entity.

Return type:

Tensor

static get_from_entity(entity, name=None)#

Parameters:

entity – The Entity from which to retrieve the Tensor.
name (str, optional) – The name of the Tensor component in the Entity.

Returns:

The Tensor instance retrieved from the Entity.

Return type:

Tensor

Get a Tensor from an Entity.

find_all_from_entity(entity)#

Parameters:: entity – The Entity from which to retrieve all Tensor instances.
Returns:: A list of Tensor instances retrieved from the Entity.
Return type:: list[Tensor]

Find all Tensor instances in an Entity.