Scenario Runner Python API Reference

Warning

The Scenario Runner Python API is currently experimental and subject to change, including incompatible changes, in future releases.

The Python API is provided by the scenario_runner_py extension module. It supports both loading existing JSON scenarios and constructing scenarios programmatically. Resource uploads and downloads use C-contiguous NumPy arrays.

Build and import the bindings

Build the bindings from a Scenario Runner source checkout:

python3 scripts/build.py --build-pylib

The extension is written to build/src by default. Add that directory to PYTHONPATH when running a Python application, or configure your IDE to use it. From the source checkout:

export PYTHONPATH="$PWD/build/src${PYTHONPATH:+:$PYTHONPATH}"

Then import the module:

import scenario_runner_py as sr

Python examples

Load a JSON scenario, replace an input buffer, and retrieve an output buffer:

# SPDX-FileCopyrightText: Copyright 2026 Arm Limited and/or its affiliates <open-source-office@arm.com>
# SPDX-License-Identifier: Apache-2.0
from pathlib import Path

import numpy as np
import scenario_runner_py as sr

sample_dir = Path(__file__).resolve().parent.parent
scenario = sr.load_scenario(sample_dir / "increment.json", work_dir=sample_dir)
input_id = scenario.get_buffer_id("input")
output_id = scenario.get_buffer_id("output")

input_values = np.array([10, 20, 30, 40], dtype=np.uint32)
scenario.upload(input_id, input_values)
scenario.run()

# Buffer downloads contain bytes; view them using the data type used by the shader.
output_values = scenario.download(output_id).view(np.uint32)
np.testing.assert_array_equal(output_values, input_values + 1)

For a programmatic scenario, create resources with a builder and retain the returned IDs for subsequent transfer operations:

# SPDX-FileCopyrightText: Copyright 2026 Arm Limited and/or its affiliates <open-source-office@arm.com>
# SPDX-License-Identifier: Apache-2.0
from pathlib import Path

import numpy as np
import scenario_runner_py as sr

sample_dir = Path(__file__).resolve().parent.parent
builder = sr.ScenarioBuilder()

shader = sr.ShaderInfo()
shader.debug_name = "increment"
shader.entry = "main"
shader.shader_type = sr.ShaderType.Glsl
shader.stage = sr.ShaderStage.Compute
shader.load_source(str(sample_dir / "increment.comp"))
shader_id = builder.add_shader(shader)

input_id = builder.add_buffer(16, debug_name="input")
output_id = builder.add_buffer(16, debug_name="output")

dispatch = sr.DispatchComputeData(shader_id)
dispatch.debug_name = "increment"
dispatch.bindings = [
    sr.TypedBinding(0, 0, input_id, sr.DescriptorType.StorageBuffer),
    sr.TypedBinding(0, 1, output_id, sr.DescriptorType.StorageBuffer),
]
dispatch.compute_dispatch.group_count_x = 4
dispatch.compute_dispatch.profile_name = dispatch.debug_name
builder.add_dispatch_compute(dispatch)

scenario = builder.build()
input_values = np.array([1, 2, 3, 4], dtype=np.uint32)
scenario.upload(input_id, input_values)
scenario.run()

output_values = scenario.download(output_id).view(np.uint32)
np.testing.assert_array_equal(output_values, input_values + 1)

Python entry points

API	Purpose
`load_scenario()`	Load and build an existing JSON scenario file.
`ScenarioJsonFactory`	Class-based form of the JSON loading API.
`ScenarioBuilder`	Register resources and commands programmatically.
`Scenario`	Upload NumPy inputs, execute commands, and download NumPy outputs.

Scenario creation and execution

scenario_runner_py.load_scenario(scenario_file: os.PathLike | str | bytes, *, work_dir: os.PathLike | str | bytes = Path('.'), output_dir: os.PathLike | str | bytes = Path('.'), options: scenario_runner_py.ScenarioOptions = ScenarioOptions()) → scenario_runner_py.Scenario

Load a JSON scenario and return a ready-to-run Scenario.

Relative resource paths use the scenario file’s parent directory unless work_dir is supplied.

class scenario_runner_py.ScenarioJsonFactory

Create scenarios from JSON descriptions.

static make(scenario_file: os.PathLike | str | bytes, *, work_dir: os.PathLike | str | bytes = Path('.'), output_dir: os.PathLike | str | bytes = Path('.'), options: scenario_runner_py.ScenarioOptions = ScenarioOptions()) → scenario_runner_py.Scenario: Load a JSON scenario and return a ready-to-run Scenario.

class scenario_runner_py.Scenario

A built scenario that owns runtime resources and commands. It can be run repeatedly.

download()

Overloaded function.

1. download(self: scenario_runner_py.Scenario, id: scenario_runner_py.BufferId) -> numpy.ndarray

Return the buffer contents as a uint8 NumPy array.

2. download(self: scenario_runner_py.Scenario, id: scenario_runner_py.TensorId) -> numpy.ndarray

Return tensor contents as a NumPy array derived from its format.

3. download(self: scenario_runner_py.Scenario, id: scenario_runner_py.ImageId) -> numpy.ndarray

Return image contents as a NumPy array derived from its format. Multi-component images use a packed dtype.

get_buffer_id(self: scenario_runner_py.Scenario, uid: str) → scenario_runner_py.BufferId: Return the buffer ID associated with a JSON resource UID.

get_image_id(self: scenario_runner_py.Scenario, uid: str) → scenario_runner_py.ImageId: Return the image ID associated with a JSON resource UID.

get_tensor_id(self: scenario_runner_py.Scenario, uid: str) → scenario_runner_py.TensorId: Return the tensor ID associated with a JSON resource UID.

run(self: scenario_runner_py.Scenario, *, repeat_count: SupportsInt | SupportsIndex = 1, dry_run: bool = False) → None: Execute the command sequence.

upload()

Overloaded function.

1. upload(self: scenario_runner_py.Scenario, id: scenario_runner_py.BufferId, data: numpy.ndarray) -> None

Copy a C-contiguous NumPy array into the buffer selected by id.

2. upload(self: scenario_runner_py.Scenario, id: scenario_runner_py.TensorId, data: numpy.ndarray) -> None

Copy a C-contiguous NumPy array into the tensor selected by id.

3. upload(self: scenario_runner_py.Scenario, id: scenario_runner_py.ImageId, data: numpy.ndarray) -> None

Copy one mip level from a C-contiguous NumPy array into the image selected by id.

Scenario builder

class scenario_runner_py.ScenarioBuilder

Define resources and commands, then build a Scenario.

add_buffer_barrier(self: scenario_runner_py.ScenarioBuilder, info: scenario_runner_py.BufferBarrierInfo) → scenario_runner_py.BufferBarrierId: Register a BufferBarrierInfo and return its barrier ID.

add_dispatch_compute(self: scenario_runner_py.ScenarioBuilder, command: scenario_runner_py.DispatchComputeData) → None: Append a DispatchComputeData command.

add_dispatch_data_graph(self: scenario_runner_py.ScenarioBuilder, command: scenario_runner_py.DispatchDataGraphData) → None: Append a DispatchDataGraphData command.

add_dispatch_data_graph_binary(self: scenario_runner_py.ScenarioBuilder, command: scenario_runner_py.DispatchDataGraphBinaryData) → None: Append a DispatchDataGraphBinaryData command.

add_dispatch_fragment(self: scenario_runner_py.ScenarioBuilder, command: scenario_runner_py.DispatchFragmentData) → None: Append a DispatchFragmentData command.

add_dispatch_optical_flow(self: scenario_runner_py.ScenarioBuilder, command: scenario_runner_py.DispatchOpticalFlowData) → None: Append a DispatchOpticalFlowData command.

add_dispatch_vgf(self: scenario_runner_py.ScenarioBuilder, command: scenario_runner_py.DispatchVgfData) → None: Append a DispatchVgfData command.

add_frame_boundary(self: scenario_runner_py.ScenarioBuilder, command: scenario_runner_py.FrameBoundaryData) → None: Append a FrameBoundaryData command.

add_graph_constant(self: scenario_runner_py.ScenarioBuilder, info: scenario_runner_py.GraphConstantInfo) → scenario_runner_py.GraphConstantResourceId: Register GraphConstantInfo and return its ID.

add_image_barrier(self: scenario_runner_py.ScenarioBuilder, info: scenario_runner_py.ImageBarrierInfo) → scenario_runner_py.ImageBarrierId: Register an ImageBarrierInfo and return its barrier ID.

add_memory_barrier(self: scenario_runner_py.ScenarioBuilder, info: scenario_runner_py.MemoryBarrierInfo) → scenario_runner_py.MemoryBarrierId: Register a MemoryBarrierInfo and return its barrier ID.

add_pipeline_barrier(self: scenario_runner_py.ScenarioBuilder, command: scenario_runner_py.PipelineBarrierData) → None: Append a PipelineBarrierData command.

add_raw_data(self: scenario_runner_py.ScenarioBuilder, info: scenario_runner_py.RawDataInfo) → scenario_runner_py.RawDataId: Register RawDataInfo and return its ID.

add_resource_to_memory_group(self: scenario_runner_py.ScenarioBuilder, group: scenario_runner_py.MemoryGroupId, resource: object) → None: Add a buffer, image, or tensor ID to an existing aliasing group.

add_shader(self: scenario_runner_py.ScenarioBuilder, info: scenario_runner_py.ShaderInfo) → scenario_runner_py.ShaderId: Register ShaderInfo and return its ID.

add_tensor_barrier(self: scenario_runner_py.ScenarioBuilder, info: scenario_runner_py.TensorBarrierInfo) → scenario_runner_py.TensorBarrierId: Register a TensorBarrierInfo and return its barrier ID.

add_vgf(self: scenario_runner_py.ScenarioBuilder, info: scenario_runner_py.VgfInfo) → scenario_runner_py.VgfId: Register VgfInfo and return its ID.

build(self: scenario_runner_py.ScenarioBuilder, *, options: scenario_runner_py.ScenarioOptions = ScenarioOptions()) → scenario_runner_py.Scenario: Consume the builder and return a ready-to-run Scenario. The builder cannot be reused.

create_memory_group(self: scenario_runner_py.ScenarioBuilder) → scenario_runner_py.MemoryGroupId: Create an aliasing group and return its ID.

Resource creation

The resource methods accept either a resource description object or convenience arguments. Both forms return the corresponding typed ID.

ScenarioBuilder.add_buffer()

Overloaded function.

1. add_buffer(self: scenario_runner_py.ScenarioBuilder, info: scenario_runner_py.BufferInfo) -> scenario_runner_py.BufferId

Register a buffer and return its ID.

2. add_buffer(self: scenario_runner_py.ScenarioBuilder, size: typing.SupportsInt | typing.SupportsIndex, *, debug_name: str = '', memory_offset: typing.SupportsInt | typing.SupportsIndex = 0) -> scenario_runner_py.BufferId

Register a buffer and return its ID.

ScenarioBuilder.add_image()

Overloaded function.

1. add_image(self: scenario_runner_py.ScenarioBuilder, info: scenario_runner_py.ImageInfo) -> scenario_runner_py.ImageId

Register an image and return its ID.

2. add_image(self: scenario_runner_py.ScenarioBuilder, shape: collections.abc.Sequence[typing.SupportsInt | typing.SupportsIndex], format: scenario_runner_py.Format, *, debug_name: str = '', is_input: bool = False, is_sampled: bool = False, is_storage: bool = False, is_color_attachment: bool = False, mips: typing.SupportsInt | typing.SupportsIndex = 1, tiling: scenario_runner_py.Tiling | None = None, memory_offset: typing.SupportsInt | typing.SupportsIndex = 0) -> scenario_runner_py.ImageId

Register an image and return its ID. The convenience overload uses format as both source and target format.

ScenarioBuilder.add_tensor()

Overloaded function.

1. add_tensor(self: scenario_runner_py.ScenarioBuilder, info: scenario_runner_py.TensorInfo) -> scenario_runner_py.TensorId

Register a tensor and return its ID.

2. add_tensor(self: scenario_runner_py.ScenarioBuilder, shape: collections.abc.Sequence[typing.SupportsInt | typing.SupportsIndex], format: scenario_runner_py.Format, *, debug_name: str = '', sparsity_dimension: typing.SupportsInt | typing.SupportsIndex = -1, descriptor_buffer_capture_replay: bool = False, tiling: scenario_runner_py.Tiling = <Tiling.Linear: 1>, memory_offset: typing.SupportsInt | typing.SupportsIndex = 0) -> scenario_runner_py.TensorId

Register a tensor and return its ID.

Python resource identifiers

Typed IDs are immutable and hashable. They are created by the methods below, not constructed directly. The value property exposes the underlying numeric identifier for inspection or debugging; it is meaningful only within its scenario.

Type	Identifies	Created by
`BufferId`	A buffer	`add_buffer()` or `get_buffer_id()`
`ImageId`	An image	`add_image()` or `get_image_id()`
`TensorId`	A tensor	`add_tensor()` or `get_tensor_id()`
`ShaderId`	Shader data	`add_shader()`
`RawDataId`	Raw binary data	`add_raw_data()`
`VgfId`	A VGF	`add_vgf()`
`GraphConstantResourceId`	A graph constant	`add_graph_constant()`
`MemoryGroupId`	A memory aliasing group	`create_memory_group()`
`ImageBarrierId`	An image barrier	`add_image_barrier()`
`BufferBarrierId`	A buffer barrier	`add_buffer_barrier()`
`TensorBarrierId`	A tensor barrier	`add_tensor_barrier()`
`MemoryBarrierId`	A memory barrier	`add_memory_barrier()`

class scenario_runner_py.BufferId

An immutable, hashable typed resource ID scoped to a scenario.

property value

Type:: int