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.

property added_to_graph

Check if the component has been added to a graph.

Returns: True if the component has been added to a graph, False otherwise.
Return type: bool

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