rstsr-lapack-ffi 0.4.0

Netlib LAPACK FFI bindings
Documentation

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 by default.

If you do not want to use dynamic loading, please disable default cargo features (--no-default-features when cargo build).

The dynamic loading will try to find proper library when your program initializes. 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.

Cargo features

Default features:

  • dynamic_loading: Supports dynamic loading.
  • blas: Inclulde BLAS bindgens.
  • cblas: Include CBLAS bindgens.
  • lapack: Include LAPACK bindgens.

Optional features:

  • 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.4

    • 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.