# OpenBLAS FFI bindings
This crate contains OpenBLAS FFI bindings.
Current FFI version is [OpenBLAS v0.3.30](https://github.com/OpenMathLib/OpenBLAS/releases/tag/v0.3.30). If you are using an older version of OpenBLAS, this crate should still work if you do not explicitly call the function that only occurs in higher version of OpenBLAS.
OpenBLAS (C/Fortran/ASM) source code is available on [github](https://github.com/OpenMathLib/OpenBLAS).
This crate is not official bindgen project. It is originally intended to serve rust tensor toolkit [RSTSR](https://github.com/RESTGroup/rstsr) and rust electronic structure toolkit [REST](https://gitee.com/RESTGroup/rest).
- **Audience**: Anyone uses OpenBLAS 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 variable `RSTSR_DYLOAD_OPENBLAS` 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_openblas_ffi::blas`, `rstsr_openblas_ffi::cblas` and `rstsr_openblas_ffi::lapack`. Sticking to using `rstsr_openblas_ffi` will make sure you are calling BLAS and LAPACK functions from OpenBLAS, instead of other BLAS vendors.
## 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 module `blas`, error code is returned by `c_int`; in module `cblas`, OpenBLAS utility functions use `c_int` for input or output.
- `lapacke`: Include LAPACKE bindgens.
- `quad_precision` and `ex_precision`: Specify type extra-precision `xdouble` type in module `blas`. Probably few people will require these features.
## Crate structure
- `header`: Header files copied (or renamed) from original source.
- `scripts`: Script to generate FFI bindgens.
- `src`: FFI bindings:
- `blas`: Corresponds to `f77blas.h` header in compiled library include (or `common_interface.h` in OpenBLAS original source code). BLAS and some LAPACK functions that implemented by OpenBLAS, no post-suffix underscore.
- `cblas`: Corresponds to `cblas.h` header. Original CBLAS included, along with OpenBLAS utility functions (e.g. `openblas_get_num_threads`) and some BLAS extensions (e.g. `cblas_zgemm_batch`).
- 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.4
- **API breaking change**: Supports and defaults to dynamic loading.
- Added `omp_set_num_threads` and `omp_get_max_threads` for convenience.