heterocl.api

heterocl.init([init_dtype])	Initialize a HeteroCL environment with configurations.
heterocl.placeholder(shape[, name, dtype])	Construct a HeteroCL placeholder for inputs/outputs.
heterocl.create_scheme(inputs, func)	Create a quantization scheme.
heterocl.create_schedule(inputs[, func])	Create a schedule for compute optimizations.
heterocl.create_schedule_from_scheme(scheme)	Create a schedule from a scheme.
heterocl.lower(schedule)	Get the generated IR of a given schedule.
heterocl.build(schedule[, target, name, stmt])	Build the executable according to the schedule and target.
heterocl.cast(dtype, expr)	Cast an expression to specified data type.
heterocl.select(cond, true, false)	Construct a select branch with the given condition.
heterocl.print(vals[, format])	Print a HeteroCL object.

init(init_dtype='int32')

Initialize a HeteroCL environment with configurations.

This API must be called each time the users write an application. Within the same HeteroCL environment, users can try different combinations of customization primitives.

Parameters

init_dtype (Type, optional) – The default data type for each variables

Examples

# app 1
hcl.init()
A = hcl.placeholder(...)
B = hcl.placeholder(...)
def app1(A, B):
    # define the algorithm for app 1
s = hcl.create_scheme([A, B], app1)
# apply customization primitives
f1 = hcl.build(s)
# execute f1

# app 2 - initialize again with a different data type
hcl.init(hcl.Float())
A = hcl.placeholder(...)
B = hcl.placeholder(...)
C = hcl.placeholder(...)
def app2(A, B, C):
    # define the algorithm for app 2
s = hcl.create_scheme([A, B, C], app2)
f2 = hcl.build(s)
# execute f2

placeholder(shape, name=None, dtype=None)

Construct a HeteroCL placeholder for inputs/outputs.

If the shape is an empty tuple, the returned value is a scalar.

Parameters

• shape (tuple) – The shape of the placeholder

• name (str, optional) – The name of the placeholder

• dtype (Type, optional) – The data type of the placeholder

Returns

Return type

Scalar or Tensor

Examples

# scalar - cannot be updated
a = hcl.placeholder((), "a")
# 1-dimensional tensor - can be updated
A = hcl.placeholder((1,), "A")

create_scheme(inputs, func)

Create a quantization scheme.

The first argument is a list of inputs to the second argument, which is a function the defines the algorithm. The numbers of arguments should match. The function will be set with attributes for later optimizations. This API returns an object that has two methods: quantize and downsize.

Parameters

• inputs (Tensor or list of Tensor) – A list of placeholders that are inputs to the algorithm. It can be a single tensor

• func (callable) – A function that defines the algorithm

Returns

Return type

Scheme

See also

scheme.Scheme.downsize(), scheme.Scheme.quantize()

Examples

A = hcl.placeholder((10,))
def algo(A):
    return hcl.compute(A.shape, lambda x: A[x]+1, "B")
s = hcl.create_scheme(A, algo)
s.downsize(algo.B, hcl.Int(8))

create_schedule(inputs, func=None)

Create a schedule for compute optimizations.

The first argument is a list of inputs to the second argument, which is a function the defines the algorithm. The numbers of arguments should match. The function will be set with attributes for later optimizations.

Parameters

• inputs (Tensor or list of Tensor) – A list of placeholders that are inputs to the algorithm. It can be a single tensor

• func (callable, optional) – A function that defines the algorithm

Returns

Return type

Schedule

See also

create_scheme(), create_schedule_from_scheme()

Notes

If the function is not provided, we can also create a schedule. However, users cannot create a quantization scheme anymore. We strongly recommend users to provide the function.

Examples

# example 1 - normal usage
A = hcl.placeholder((10,))
def algo(A):
    return hcl.compute(A.shape, lambda x: A[x]+1, "B")
s = hcl.create_schedule(A, algo)
s[algo.B].unroll(algo.B.axis[0])

# example 2 - no function is provided
A = hcl.placeholder((10,))
B = hcl.compute(A.shape, lambda x: A[x]+1)
s = hcl.create_schedule(A)
s[B].unroll(B.axis[0])

create_schedule_from_scheme(scheme)

Create a schedule from a scheme.

Parameters

scheme (Scheme) – The quantization scheme that will be applied to the compute schedule

Returns

Return type

Schedule

See also

create_schedule(), create_scheme()

Examples

A = hcl.placeholder((10,))
def algo(A):
    return hcl.compute(A.shape, lambda x: A[x]+1, "B")
sm = hcl.create_scheme(A, algo)
sl = hcl.create_schedule_from_scheme(sm)

lower(schedule)

Get the generated IR of a given schedule.

Parameters

schedule (Schedule) – The schedule that will be used to generate the IR

Returns

Return type

Stmt

build(schedule, target=None, name='default_function', stmt=None)

Build the executable according to the schedule and target.

The default target is llvm (i.e., CPU execution). If stmt is specified, the statements created by HeteroCL APIs will be ignored.

Parameters

• schedule (Schedule) – The schedule to be built

• target (str, optional) – The target of the executable

• name (str, optional) – The name of the generated function

• stmt (Stmt, optional) – The built statement

Returns

Return type

tvm.module.Module

cast(dtype, expr)

Cast an expression to specified data type.

Parameters

• dtype (Type) – The target data type

• expr (Expr) – The expression to be cast

Returns

Return type

Expr

select(cond, true, false)

Construct a select branch with the given condition.

It is similar to the following Python expression.

ret = true if cond else false

Parameters

• cond (Expr) – The condition

• true (Expr) – The true branch

• false (Expr) – The false branch

Returns

Return type

Expr

print(vals, format='')

Print a HeteroCL object.

Parameters

• vals (Expr or list of Expr) – The values to be printed

• format (string, optional) – The printing format similar to printf

Returns

Return type

None