lua-api-reference.md

This section describes the Lua APIs of PPLNN. Refer to pplnn.lua for usage examples and lua_pplnn.cc for exported symbols.

Common APIs in luappl.nn

TensorShape

dims = TensorShape:GetDims()

Returns an array of dimensions.

TensorShape:SetDims(dims)

Sets dims of the tensor.

data_type = TensorShape:GetDataType()

Returns the data type of elements in tensor. Data types are defined in luappl.common.

data_format = TensorShape:GetDataFormat()

Returns the data format of tensor. Data formats are defined in luappl.common.

is_scalar = TensorShape:IsScalar()

Tells whether a tensor is a scalar.

Tensor

name_str = Tensor:GetName()

Returns the tensor's name.

tensor_shape = Tensor:GetShape()

Returns a TensorShape object of the tensor.

ret_code = Tensor:ConvertFromHost(buffer, dims, data_type)

Copies data to the tensor from buffer shaped as dims and data_type. ret_code is an instance of RetCode defined in luappl.common. data_type is defined in luappl.common.

tensor_data = Tensor:ConvertToHost()

Copies tensor's data to host in NDARRAY format. Shape and data type can be retrieved by Tensor:GetShape():GetDims() and Tensor:GetShape():GetDataType() respectively.

Engine

name_str = Engine:GetName()

Returns engine's name.

onnx.RuntimeBuilderFactory

runtime_builder = onnx.RuntimeBuilderFactory:Create()

Creates an onnx.RuntimeBuilder instance.

onnx.RuntimeBuilder

status = runtime_builder:LoadModelFromFile(onnx_model_file)

loads an ONNX model from the specified file.

resources = RuntimeBuilderResources()
resources.engines = engines
status = runtime_builder:SetResources(resources)

where engines is a list of Engine instances that are used to preprocess and evaluate the model.

status = runtime_builder:Preprocess()

does some preparations before creating Runtime instances.

runtime = RuntimeBuilder:CreateRuntime()

creates a Runtime instance for inferencing.

Runtime

input_count = Runtime:GetInputCount()

Returns the number of model inputs.

input_tensor = Runtime:GetInputTensor(idx)

Returns the input tensor in position idx, which is in range [0, input_count).

ret_code = Runtime::Run()

Evaluates the model. ret_code is an instance of RetCode defined in luappl.common.

output_count = Runtime:GetOutputCount()

Returns the number of model outputs.

output_tensor = Runtime:GetOutputTensor(idx)

Returns the output tensor in position idx, which is in range [0, output_count).

Device Specific APIs in luappl.nn

x86

EngineOptions

Refer to engine_options.h for more details.

EngineFactory

x86_options = x86.EngineOptions()
x86_engine = x86.EngineFactory:Create(x86_options)

Creates an Engine instance running on x86-64 compatiable CPUs.

CUDA

EngineOptions

Refer to engine_options.h for more details.

EngineFactory

cuda_options = cuda.EngineOptions()
cuda_engine = cuda.EngineFactory:Create(cuda_options)

Creates an Engine instance running on NVIDIA GPUs.

Other Utilities

version_str = luappl.nn.GetVersionString()

Returns the version string of current version.

msg_str = luappl.common.GetRetCodeStr(ret_code)

Returns a human-readable message of ret_code.

luappl.common.SetLoggingLevel(log_level)
log_level = luappl.common.GetLoggingLevel()

Sets and gets the current logging level respectively. Logging levels are defined in luappl.common.