MIGraphX Python API reference

MIGraphX Python API reference#

2026-10-12

9 min read time

Applies to Linux

shape#

class migraphx.shape(type, lens, strides=None, dyn_dims)#

Describes the shape of a tensor. This includes size, layout, and data type. Use dyn_dims for a dynamic shape.

migraphx.type()#

An integer that represents the type.

Return type:

int

migraphx.lens()#

A list of the lengths of the shape.

Return type:

list[int]

migraphx.strides()#

A list of the strides of the shape.

Return type:

list[int]

migraphx.elements()#

The number of elements in the shape.

Return type:

int

migraphx.dyn_dims()#

The dynamic dimensions of the shape.

Return type:

list[dynamic_dimension]

migraphx.bytes()#

The number of bytes the shape uses.

Return type:

int

migraphx.type_size()#

The number of bytes one element uses

Return type:

int

migraphx.ndim()#

The number of dimensions for the shape.

Return type:

int

migraphx.packed()#

Returns true if the shape is packed.

Return type:

bool

migraphx.transposed()#

Returns true if the shape is transposed.

Return type:

bool

migraphx.broadcasted()#

Returns true if the shape is broadcasted.

Return type:

bool

migraphx.dynamic()#

Returns true if the shape is dynamic.

Return type:

bool

migraphx.standard()#

Returns true if the shape is a standard shape. That is, the shape is both packed and not transposed.

Return type:

bool

migraphx.scalar()#

Returns true if all strides are equal to 0 (scalar tensor).

Return type:

bool

migraphx.symbolic()#

Returns true if every dimension of the shape is symbolic.

Return type:

bool

migraphx.dyn_strides()#

The symbolic strides of the shape, as expression strings. Empty unless shape.symbolic() is true.

Return type:

list[str]

dynamic_dimension#

class migraphx.dynamic_dimension(min, max, optimals)#

Constructs a dynamic_dimension from a minimum, a maximum, and optionally a set of optimals.

class migraphx.dynamic_dimension(expression, symbols={})

Constructs a symbolic dynamic_dimension by parsing an expression string. Each bracketed interval after a variable is a constraint, and an optional final braced list contains its optimals. The optional symbols map can still bind bounds to bare variable names.

Parameters:

  • expression (str) – The expression to parse, such as "n[1..8] * 3 + 1".

  • symbols (dict[str, dynamic_dimension]) – The bounds to bind each name to.

migraphx.is_fixed()#

Returns true if the dynamic_dimension is fixed.

:rtype : int

migraphx.is_symbolic()#

Returns true if the dynamic_dimension carries a symbolic expression.

Return type:

bool

migraphx.min#

The smallest size the dimension can take.

migraphx.max#

The largest size the dimension can take.

migraphx.optimals#

The set of sizes to optimize the dimension for.

migraphx.expression#

The expression giving the size of the dimension, or None when the dimension is range-based.

symbolic shapes#

A dynamic dimension can be a symbolic expression rather than a plain range. Expressions are written as strings, with each variable carrying its constraints and optimals inline. This is also the spelling program.to_py() emits:

s = migraphx.shape(type="float_type",
                   dyn_dims=["n[1..8]{2, 4}", "3"])

A symbol name has to be a valid identifier, that is a letter or an underscore followed by letters, digits or underscores, because the expression has to survive being parsed back. Names taken from an ONNX model are rewritten to fit. For example, an unnamed dynamic axis 0 of an input named 0 yields _0_d0, while a dim_param of batch.size yields batch_size.

Append each interval in brackets when a symbol asserts more than one constraint, which is what adding two differently bounded uses of the same name produces. Append the optional optimals in braces:

"n[1..20][2..10]{4}"

To specify optimals without constraints, append the braced list directly, for example "n{2, 4}".

A dynamic shape’s dimensions must be either all symbolic or all range-based. Use a symbolic literal such as "3" for a fixed axis in a symbolic shape rather than mixing in dynamic_dimension(3, 3).

Pass dyn_strides for a transposed or broadcasted layout; without it an all-symbolic shape is given packed standard strides. Each stride is also a self-contained symbolic expression:

s = migraphx.shape(type="float_type",
                   dyn_dims=["n[1..8]", "3"],
                   dyn_strides=["1", "n[1..8]"])

argument#

class migraphx.argument(data)#

Constructs an argument from a python buffer. This can include numpy arrays.

migraphx.data_ptr()#

Returns the address to the underlying argument data.

Return type:

int

migraphx.get_shape()#

Returns the shape of the argument.

Return type:

shape

migraphx.tolist()#

Converts the elements of the argument to a python list.

Return type:

list

migraphx.generate_argument(s, seed=0)#

Generates an argument with random data.

Parameters:

  • s (shape) – Shape of argument to generate.

  • seed (int) – The seed used for random number generation.

Return type:

argument

migraphx.fill_argument(s, value)#

Fills argument of shape s with the given value.

Parameters:

  • s (shape) – Shape of argument to fill.

  • value (int) – Value to fill in the argument.

Return type:

argument

migraphx.create_argument(s, values)#

Creates an argument of shape s with a set of values.

Parameters:

  • s (shape) – Shape of argument to create.

  • values (list) – Values to put in the argument. Must be the same number of elements as the shape.

Return type:

argument

migraphx.argument_from_pointer(shape, address)#

Creates argument from data stored in given address without copy.

Parameters:

  • shape (shape) – Shape of the data stored in address.

  • address (long) – Memory address of data from another source

Return type:

argument

static argument.save(arg, filename)#

Saves argument to a file encoded in msgpack format.

Parameters:

  • arg (argument) – Argument to save out to.

  • filename (str) – Path of file to save out to.

static argument.load(filename)#

Load argument from a file encoded in msgpack format.

Parameters:

filename (str) – Path of file to load.

Return type:

argument

target#

class migraphx.target#

This represents the compilation target.

migraphx.get_target(name)#

Constructs the target.

Parameters:

name (str) – The name of the target to construct. This can either be ‘gpu’ or ‘ref’.

Return type:

target

module#

migraphx.print()#

Prints the contents of the module as list of instructions.

migraphx.add_instruction(op, args, mod_args=[])#

Adds instruction into the module.

Parameters:

  • op (operation) – ‘migraphx.op’ to be added as instruction.

  • args (list[instruction]) – list of inputs to the op.

  • mod_args (list[module]) – optional list of module arguments to the operator.

:rtype instruction

migraphx.add_literal(data)#

Adds constant or literal data of provided shape into the module from python buffer which includes numpy array.

Parameters:

data (py::buffer) – Python buffer or numpy array

:rtype instruction

migraphx.add_parameter(name, shape)#

Adds a parameter to the module with the provided name and shape.

Parameters:

  • name (str) – name of the parameter.

  • shape (shape) – shape of the parameter.

:rtype instruction

migraphx.add_return(args)#

Adds a return instruction into the module.

Parameters:

args (list[instruction]) – instruction arguments which need to be returned from the module.

:rtype instruction

program#

class migraphx.program#

Represents the computation graph to be compiled and run.

migraphx.clone()#

Makes a copy of the program.

Return type:

program

migraphx.get_parameter_names()#

Gets all the input argument’s or parameter’s names to the program as a list.

:rtype list[str]

migraphx.get_parameter_shapes()#

Gets the shapes of all the input parameters in the program.

Return type:

dict[str, shape]

migraphx.get_output_shapes()#

Gets the shapes of the final outputs of the program.

Return type:

list[shape]

migraphx.compile(t, offload_copy=True, fast_math=True, exhaustive_tune=False, advance_backend_options={})#

Compiles the program for the target and optimizes it.

Parameters:

  • t (target) – Compilation target for the program.

  • offload_copy (bool) – For targets with offloaded memory(such as the gpu), this will insert instructions during compilation to copy the input parameters to the offloaded memory and to copy the final result from the offloaded memory back to main memory.

  • fast_math (bool) – Optimize math functions to use faster approximate versions. There may be slight accuracy degredation when enabled.

  • exhaustive_tune – Flag to enable exhaustive search to find the fastest version of generated kernels for selected backend.

  • advance_backend_options (dict) – Backend-specific compilation options. Options unknown to the target are ignored.

migraphx.get_main_module()#

Gets main module of the program.

:rtype module

migraphx.create_module(name)#

Creates and adds a module with the provided name into the program.

:param str name : name of the new module. :rtype module

migraphx.verify(target, mode=program_verify_mode.outputs, params={}, **options)#

Compares a program with the ref target using the selected verification mode.

Parameters:

  • target (target) – Target implementation to verify.

  • mode (program_verify_mode) – Verification mode.

  • params (dict[str, argument]) – Concrete input arguments. Dynamic parameters require explicit arguments.

  • options – Verification options such as rms_tol, atol, rtol, precision, ref_use_double, and compiled_model.

Return type:

program_verify_result

migraphx.run(params)#

Runs the program.

Parameters:

params (dict[str, argument]) – Map of the input parameters to be used when running the program.

Returns:

The result of the last instruction.

Return type:

list[argument]

migraphx.sort()#

Sorts the modules of the program for the instructions to appear in topologically sorted order.

migraphx.quantize_fp16(prog, ins_names=['all'])#

Quantizes the program to use fp16.

Parameters:

  • prog (program) – Program to quantize.

  • ins_names (list[str]) – List of instructions to quantize.

migraphx.quantize_bf16(prog, ins_names=['all'])#

Quantizes the program to use bf16.

Parameters:

  • prog (program) – Program to quantize.

  • ins_names (list[str]) – List of instructions to quantize.

migraphx.quantize_int8(prog, t, calibration=[], ins_names=['dot', 'convolution'])#

Quantizes the program to use int8.

Parameters:

  • prog (program) – Program to quantize.

  • t (target) – Target to be used to run the calibration data.

  • calibration (list[dict[str, argument]]) – Calibration data used to decide the parameters to the int8 optimization.

  • ins_names (list[str]) – List of instructions to quantize.

migraphx.autocast_fp8(prog)#

Auto-convert FP8 parameters and return values to Float for an MIGraphX program.

Parameters:

prog (program) – Program to auto-convert parameters/return values.

op#

parse_onnx#

migraphx.parse_onnx(filename, default_dim_value=1, map_input_dims={}, skip_unknown_operators=false, print_program_on_error=false, max_loop_iterations=10, limit_max_iterations=65535)#

Loads and parses an ONNX file.

Parameters:

  • filename (str) – Path to file.

  • default_dim_value (str) – default dimension to use (if not specified in onnx file).

  • default_dyn_dim_value (dynamic_dimension) – default dynamic_dimension value to use.

  • map_input_dims (str) – Explicitly specify the dims of an input.

  • map_dyn_input_dims (list[dynamic_dimension]) – Explicitly specify the dynamic_dimensions of an input.

  • skip_unknown_operators (str) – Continue parsing onnx file if an unknown operator is found.

  • print_program_on_error (str) – Print program if an error occurs.

  • max_loop_iterations (int) – Maximum iteration number for the loop operator if trip count is not set.

  • limit_max_iterations (int) – Maximum iteration limit for the loop operator.

Return type:

program

parse_tf#

migraphx.parse_tf(filename, is_nhwc=True, batch_size=1, map_input_dims=dict(), output_names=[])#

Loads and parses a tensorflow protobuf file.

Parameters:

  • filename (str) – Path to file.

  • is_nhwc (bool) – Use nhwc as default format.

  • batch_size (str) – default batch size to use (if not specified in protobuf).

  • map_input_dims (dict[str, list[int]]) – Optional arg to explictly specify dimensions of the inputs.

  • output_names (list[str]) – Optional argument specify names of the output nodes.

Return type:

program

load#

migraphx.load(filename, format='msgpack')#

Loads a MIGraphX program.

Parameters:

  • filename (str) – Path to file.

  • format (str) – Format of file. Valid options are msgpack or json.

Return type:

program

save#

migraphx.save(p, filename, format='msgpack')#

Saves a MIGraphX program.

Parameters:

  • p (program) – Program to save.

  • filename (str) – Path to file.

  • format (str) – Format of file. Valid options are msgpack or json.

Contents