Crate rstsr_mkl_ffi

Crate rstsr_mkl_ffi 

Source
Expand description

§Intel oneAPI MKL FFI bindings

This crate contains Intel oneAPI MKL (Math Kernel Library) FFI bindings.

Current FFI version is oneAPI MKL 2025.2 (link to download page). If you are using an older version of oneAPI MKL, this crate should still work if you do not explicitly call the function that only occurs in higher version of oneAPI MKL.

Feature Not Complete: oneAPI MKL is a large collection of math functions. This crate currently only have following bindgens:

  • service (mkl_service.h)
  • blas, cblas
  • lapack, lapacke

We surely want to perform more bindgens (such as paradiso, trans, poisson, fft, dft, etc.) in future; but these are not of priority for project REST and RSTSR. If you wish to put these bindgens in this crate, currently you can file an issue, and we will quickly realize the bindgen of other features in oneAPI MKL.

Intel oneAPI MKL is freely distributed in binary (along with header), not source code. Please note the license of oneAPI (Intel Simplified Software License) is not fully free software.

This crate is not official bindgen project. It is originally intended to serve rust tensor toolkit RSTSR and rust electronic structure toolkit REST.

  • Audience: Anyone uses MKL function may also find it useful, not only RSTSR or REST program developers.
  • Pure Extern or Dynamic Loading: This crate supports either pure extern (usual FFI, requires dynamic or static linking) and dynamic-loading, by cargo feature dynamic_loading.

§Dynamic loading

This crate supports dynamic loading.

If you want to use dynamic loading, please enable cargo feature dynamic_loading when cargo build.

The dynamic loading will try to find proper library when your program initializes.

  • This crate will automatically detect proper libraries (libmkl_rt.so), if these libraries are in environmental path LD_LIBRARY_PATH (Linux) DYLD_LIBRARY_PATH (Mac OS), PATH (Windows).
  • If you want to override the library to be loaded, please set these shell environmental variable RSTSR_DYLOAD_MKL to the dynamic library path.

NOTE: When you call BLAS and LAPACK functions with dynamic loading, please DO NOT USE other crates (such as rstsr_lapack_ffi). Please make sure you are only using rstsr_mkl_ffi::blas, rstsr_mkl_ffi::cblas and rstsr_mkl_ffi::lapack. Sticking to using rstsr_mkl_ffi will make sure you are calling BLAS and LAPACK functions from oneAPI MKL, instead of other BLAS vendors.

If you encountered large compile time or disk consumption, you may consider add these lines in your Cargo.toml:

[profile.dev.package.rstsr-mkl-ffi]
opt-level = 0
debug = false

If you encountered some functions not found when using dynamic linking, especially functions like exp, log that should be in libm.so, then you may need to explicitly link libm.so in build.rs by this way:

println!("cargo:rustc-link-arg=-Wl,--no-as-needed,-lm");

§Cargo features

Default features:

  • blas: Inclulde BLAS bindgens.
  • cblas: Include CBLAS bindgens.
  • lapack: Include LAPACK bindgens.

Optional features:

  • dynamic_loading: Supports dynamic loading.
  • ilp64: Use int64_t for dimension specification, or lapack error code types if this feature specified. Otherwise, use int32_t.
    • Please note that in module blas, error code is returned by c_int; in module cblas, oneAPI MKL utility functions use c_int for input or output.
  • lapacke: Include LAPACKE bindgens.

§Crate structure

  • header: Header files copied (or renamed) from original source.
  • scripts: Script to generate FFI bindgens.
  • In each bindgens, the following files are usually automatically generated by scripts:
    • ffi_base.rs: Basic type, enum, struct definitions.
    • ffi_extern.rs: Unsafe extern “C” bindgen functions. Only activated when not dynamic loading.
    • dyload_struct.rs: Struct Lib for dynamic loading.
    • dyload_initializer.rs: The initialization function of Lib for dynamic loading.
    • dyload_compatible.rs: Unsafe bindgen function that is compatible to that of ffi_extern.rs. Only activated when dynamic loading.
    • special case of cblas::ffi_base: the enums CBLAS_TRANSPOSE, CBLAS_UPLO, etc comes from crate rstsr_lapack_ffi for convenience. This crate depends on rstsr_lapack_ffi for those definitions of enums.

§Changelog

  • v0.2.0

    • API Breaking: Now cargo feature dynamic_loading is not default.

  • v0.1.5

    • Enhancements: Updated panic information.

  • v0.1.4

    • Docs Update
    • Fix: Fix ilp64 integer type definition in cblas module.

  • v0.1.2

    • API Breaking: Change CBLAS enum definition to crate rstsr-cblas-base.

  • v0.1.1

    • Fix: Add compatibility of definition of blas_int and lapack_int.

  • v0.1.0

    • Initialize: Added blas, cblas, lapack, lapacke bindgens.

Modules§

blas
cblas
lapack
mkl_types
service

Constants§

CRATE_NAME
LIB_NAME
LIB_NAME_LINK
LIB_NAME_SHOW