SparseIR C-API

C-compatible interface to the SparseIR Rust library.

Overview

This crate provides a libsparseir-compatible C API for the SparseIR library, designed as a drop-in replacement for the C++ implementation.

Language Support

• Julia ✅ (tested)
• Python (via ctypes/cffi)
• Fortran (via ISO_C_BINDING)
• C/C++

Compatibility with libsparseir C++ 🔄

This API is 100% compatible with the libsparseir C++ library:

Why choose Rust over C++?

• 🔒 Memory safety - No use-after-free, no double-free
• 🛡️ Panic safety - catch_unwind() prevents crashes
• 🚀 Zero-cost abstractions - Same performance as C++
• 📦 Easy deployment - Single static library, no C++ runtime needed

Features

Currently Implemented ✅

• Kernel API (5 functions) - libsparseir compatible
  • spir_logistic_kernel_new() - Create LogisticKernel
  • spir_reg_bose_kernel_new() - Create RegularizedBoseKernel
  • spir_kernel_release() - Free kernel
  • spir_kernel_get_lambda() - Get λ parameter
  • spir_kernel_compute() - Compute K(x, y)

Error Handling 🛡️

All C-API functions use catch_unwind() to prevent panics from crossing the FFI boundary:

• Returns error codes instead of panicking
• Process remains stable even on internal errors
• Safe for production use

Building

# Build shared library (.dylib on macOS, .so on Linux, .dll on Windows)
# The C header is automatically generated by cbindgen during build
cargo build --release

# Run tests
cargo test

Header Generation

The C header (include/sparseir.h) is automatically generated from Rust source code using cbindgen:

• Build time: Header is regenerated automatically when Rust sources change
• Manual regeneration: cargo build (header is created by build.rs)
• Configuration: See cbindgen.toml for generation settings

Do not edit the generated header manually - edit the Rust source code instead!

Usage Examples

Julia

# Load library
const lib = "../target/release/libsparse_ir_capi.dylib"

# Create kernel
kernel_ptr = Ref{Ptr{Cvoid}}()
status = ccall((:spir_kernel_logistic_new, lib),
               Int32, (Float64, Ref{Ptr{Cvoid}}),
               10.0, kernel_ptr)

# Compute kernel value
result = Ref{Float64}()
status = ccall((:spir_kernel_compute, lib),
               Int32, (Ptr{Cvoid}, Float64, Float64, Ref{Float64}),
               kernel_ptr[], 0.5, 0.5, result)

println("K(0.5, 0.5) = ", result[])

# Release
ccall((:spir_kernel_release, lib), Cvoid, (Ptr{Cvoid},), kernel_ptr[])

See examples/test_julia.jl for a complete example.

C

#include "sparseir.h"
#include <stdio.h>

int main() {
    // libsparseir compatible API
    int status;
    spir_kernel* kernel = spir_logistic_kernel_new(10.0, &status);

    if (kernel == NULL || status != SPIR_COMPUTATION_SUCCESS) {
        fprintf(stderr, "Failed to create kernel: status = %d\n", status);
        return 1;
    }

    double result;
    status = spir_kernel_compute(kernel, 0.5, 0.5, &result);
    printf("K(0.5, 0.5) = %f\n", result);

    spir_kernel_release(kernel);
    return 0;
}

Testing

Run the Julia example:

cd examples
julia test_julia.jl

Memory Management

All objects returned by *_new() functions must be released with their corresponding *_release() function:

• spir_kernel_release()
• (more to come: spir_basis_release(), etc.)

Error Codes

Implementation Status

• Kernel API (5/5 functions) ✅
• SVE API (0/10 functions)
• Basis API (0/15 functions)
• Sampling API (0/15 functions)
• DLR API (0/8 functions)

See C-API_IMPLEMENTATION_PLAN.md for details.

Architecture

┌──────────────┐
│ Julia/Python │  ← High-level languages
└──────┬───────┘
       │ ccall/ctypes
┌──────▼───────┐
│   C-API      │  ← This crate (FFI boundary)
│ catch_unwind │  ← Panic protection
└──────┬───────┘
       │
┌──────▼───────┐
│ sparseir-rust│  ← Core Rust implementation
└──────────────┘

Safety Features

1. Input Validation - User errors return error codes (don't panic)
2. Panic Catching - catch_unwind() at FFI boundary prevents UB
3. Arc-based Sharing - Efficient memory management for large objects
4. Type Safety - Opaque pointers hide implementation details

License

MIT