Netlib LAPACK FFI bindings

This crate contains netlib (reference) LAPACK FFI bindings.

Current FFI version is LAPACK v3.12.1. If you are using an older version of LAPACK, this crate should still work if you do not explicitly call the function that only occurs in higher version of LAPACK.

Netlib LAPACK (C/Fortran) source code is available on github.

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 BLAS and LAPACK 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, 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 variables to the dynamic library path:
  • RSTSR_DYLOAD_BLAS for rstsr_lapack_ffi::blas;
  • RSTSR_DYLOAD_CBLAS for rstsr_lapack_ffi::cblas;
  • RSTSR_DYLOAD_LAPACK for rstsr_lapack_ffi::lapack;
  • RSTSR_DYLOAD_LAPACKE for rstsr_lapack_ffi::lapacke and rstsr_lapack_ffi::lapacke_utils.

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

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

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 LAPACKE, matrix layout (mostly the first argument in LAPACKE functions) is always core::ffi::c_int, dependent to c compiler.
• lapacke: Include LAPACKE bindgens.
• lapacke_utils: Include additional utility functions of LAPACKE bindgens.

Crate structure

• header: Header files copied (or renamed) from original source.
• scripts: Script to generate FFI bindgens.
• src: FFI bindings:
  • blas
  • cblas
  • lapack
  • lapacke
  • lapacke_util
• 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.

Changelog

• v0.5.0

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

• v0.4.3

  • Additional FFIs: Functions (such as ddot_) to the subroutine counterparts (such as ddotsub_). Some BLAS vendors just provide functions instead of subroutines.
  • Enhancements: Updated panic information.

• v0.4.2

  • Docs Update

• v0.4.1

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

• v0.4.0

  • API breaking change: Supports and defaults to dynamic loading.

• v0.2

  • API breaking change: In v0.1, Fortran strlen option is included in f77blas and lapack binding. In v0.2, these arguments are muted. So for example, In v0.1 dgemm_ will have 15 arguments: 13 arguments of usual usage + 2 arguments denotes string length of transa and transb arguments. In v0.2, dgemm_ will have 13 arguments, the same to usual usage of Fortran equilvant.