poc_kokkos_rs/lib.rs
1//! # Kokkos-rs: A Proof-of-Concept
2//!
3//! ## Scope of the Project
4//!
5//! The goal of this project is not to produce an entire Kokkos implementation nor to
6//! replicate the existing C++ library. While the current C++ source code is interesting
7//! to use as inspiration, the main reference is the model description.
8//!
9//! Additionally, because of language specific features (Rust strict compilation rules,
10//! C++ templates), you can expect the underlying implementation of concepts to be
11//! vastly different.
12//!
13//!
14//! ## Quickstart
15//!
16//! The PoC itself is a library, but you can run benchmarks and examples out of the box:
17//!
18//! ```bash
19//! # all benchmarks
20//! cargo bench
21//! # a specific benchmark
22//! cargo bench --bench <BENCHMARK>
23//! # a specific example
24//! cargo run --example <EXAMPLE>
25//! ```
26//!
27//! Generate local documentation:
28//!
29//! ```bash
30//! cargo doc --no-deps --open
31//! ```
32//!
33//! Note that some elements of the documentation are feature specific.
34//!
35//! ## Compilation
36//!
37//! ### Features
38//!
39//! Using `features`, the crate can be compiled to use different backend for execution of parallel section.
40//! These can also be enabled in benchmarks.
41//!
42//! ```bash
43//! cargo build --features <FEATURE>
44//! ```
45//!
46//! Available features:
47//!
48//! - `rayon`: Uses the [rayon][2] crate to handle parallelization on CPU.
49//! - `threads` : Uses [`std::thread`] methods to handle parallelization on CPU.
50//! - `gpu`: Currently used as a way to gate GPU usage as this cannot be done in pure Rust.
51//!
52//! ### C++ Interoperability
53//!
54//! The build script will read the `CXX` environment variable to choose which C++ compiler to use
55//! for Rust/C++ interop. Note that the crate itself does not currently use C++ code, only examples
56//! do.
57//!
58//! #### Known issues
59//!
60//! - On MacOs: Does not work with Apple Clang
61//! - Solution: Homebrew Clang or tinker with flags to get OpenMP to work
62//! - On MacOs: XCode 15.0 was shipped with a broken `ld`
63//! - Solution: pass the flag `-ld_classic` to the linker. Note that this flag isn't
64//! recognized by the `ld` of previous versions of XCode. The line needed is
65//! written in the `build.rs` script, it just needs to be uncommented if necessary.
66//!
67//! [1]: https://kokkos.github.io/kokkos-core-wiki/index.html
68//! [2]: https://docs.rs/rayon/latest/rayon/
69
70//#![feature(type_alias_impl_trait)]
71
72pub mod functor;
73pub mod routines;
74pub mod view;