churon: ONNX Runtime Integration for R

churon provides R bindings for ONNX Runtime, enabling high-performance machine learning inference with ONNX models.

Features

• 🚀 High Performance: Core logic implemented in Rust for speed
• 🛡️ Memory Safety: Rust's memory safety guarantees
• 🔧 Comprehensive Error Handling: Detailed error messages and validation
• 🌐 Multiple Execution Providers: CUDA, TensorRT, DirectML, OneDNN, CoreML, CPU support (on supported platforms)
• 📦 Bundled Example Models: MNIST included for testing

Installation

System Requirements

• R (>= 4.0.0)
• Supported platforms: macOS (ARM64), Linux (x64/ARM64), Windows (x64)

Install from R-universe (Recommended)

Pre-built binaries are available from R-universe, which means no Rust toolchain required:

install.packages('churon', repos = c('https://mrchypark.r-universe.dev', 'https://cloud.r-project.org'))

Install from GitHub

If you prefer to build from source (requires Rust >= 1.88.0):

devtools::install_github("mrchypark/churon")

Quick Start

Basic Usage

library(churon)

# Download ONNX Runtime once after installing churon
if (!onnx_runtime_is_installed()) {
  install_onnx_runtime()
}

# Check available example models
models <- onnx_example_models()
print(models)

# Create a session with the example MNIST model
session <- onnx_example_session("mnist")

# Get model information
input_info <- onnx_input_info(session)
output_info <- onnx_output_info(session)

print(input_info[[1]]$get_name())     # Input tensor name
print(input_info[[1]]$get_shape())    # Input tensor shape
print(input_info[[1]]$get_data_type()) # Input tensor data type

# Run inference
input_name <- input_info[[1]]$get_name()
input_shape <- input_info[[1]]$get_shape()  # c(1, 1, 28, 28) for MNIST

# Create random input (28x28 grayscale image)
input_data <- array(rnorm(prod(input_shape)), dim = input_shape)
result <- onnx_run(session, setNames(list(input_data), input_name))

# Result is class probabilities
cat("Predicted digit:", which.max(result[[1]]) - 1, "\n")

Using Custom ONNX Models

library(churon)

# Load any ONNX model
session <- onnx_session("path/to/your/model.onnx")

# Get expected input/output information
input_info <- onnx_input_info(session)
output_info <- onnx_output_info(session)

# Run inference with your data
inputs <- list()
inputs[[input_info[[1]]$get_name()]] <- your_data
outputs <- onnx_run(session, inputs)

Session Management

# Create session with default providers
session <- onnx_session("model.onnx")

# Get available providers (note: may return limited set on current platform)
providers <- onnx_providers(session)
cat("Available providers:", paste(providers, collapse = ", "), "\n")

# Get model path
model_path <- onnx_model_path(session)

Safe Session Creation with Error Handling

# Safe session creation with automatic error handling
session <- safe_onnx_session("model.onnx")

if (!is.null(session)) {
  # Session created successfully
  result <- onnx_run(session, inputs)
} else {
  cat("Failed to create session\n")
}

# Safe inference with monitoring
result <- safe_onnx_run(session, inputs, monitor_performance = TRUE)

API Reference

Core Functions

Function	Description
onnx_session(model_path, providers = NULL)	Create an ONNX Runtime session
onnx_run(session, inputs)	Run inference with input data
onnx_input_info(session)	Get input tensor information
onnx_output_info(session)	Get output tensor information
onnx_providers(session)	Get available execution providers

Example Models

Function	Description
onnx_example_models()	List bundled example models
onnx_example_session(model_name)	Create session with example model

Utility Functions

Function	Description
install_onnx_runtime(version)	Download and install ONNX Runtime
find_model_path(model_name)	Find full path to a model file
get_onnx_runtime_info()	Get ONNX Runtime version info
check_onnx_runtime_available()	Check if ONNX Runtime is available
safe_onnx_session()	Create session with error handling
safe_onnx_run()	Run inference with error handling

Current Status

✅ Fully Working Features

• ONNX model loading and session management
• Model metadata extraction and querying
• Tensor conversion (f32, f64 support)
• Inference execution with multiple execution providers
• Comprehensive error handling and validation
• Bundled MNIST model for testing

⚠️ Limitations

• Platform Support: Currently optimized for macOS ARM64
• Execution Providers: Some providers (CUDA, TensorRT) require additional system libraries
• Performance Features: Advanced optimization features pending implementation

Contributing

1. Fork this repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

• ONNX Runtime team
• extendr project
• R community