coaster_nn/
lib.rs

1//! Provides a [Coaster][coaster] Plugin, to extend Coaster with Neural Network related
2//! operations such as convolutions, pooling, ReLU, etc. A full list of operations provided by this Plugin,
3//! can be found at the [provided Operations section](#operations).
4//!
5//! ## Overview
6//!
7//! This Coaster Plugin extends Coaster's Backend with NN related methods/operations. This allows
8//! you to run, these operations (and therefore your application) on your local machine as well as on servers,
9//! mobiles or any other machine (as if they were written for common CPU execution), while
10//! receiving the significant performance increases (usually one-to-two orders of magnitutde), by
11//! executing the operations on special purpose hardware such as GPUs - if they are available. Usage examples
12//! can be found in the next section.
13//!
14//! The architecture of a Plugin is quite easy. It defines one Plugin Trait, in this case the `NN`
15//! trait, which implements basic functionality for initialization and multiple Plugin Operation Traits which define the
16//! methods which are going to be available on the Backed, as the Plugin Trait as well as the Plugin Operations Traits
17//! are implemented for the Coaster Backends (CUDA, OpenCL, Native). The operations take as arguments one or many
18//! SharedTensors, holding the data over which the operation should happen, and none or one Operation Configuration.
19//!
20//! ## Usage
21//!
22//! An example on how to write some data into a SharedTensor and compute the result of the
23//! sigmoid function for each value:
24//!
25//! ```rust
26//! # #![allow(dead_code)]
27//! extern crate coaster as co;
28//! extern crate coaster_nn as nn;
29//! # #[cfg(feature = "cuda")]
30//! # mod cuda {
31//! use co::prelude::*;
32//! use co::frameworks::native::flatbox::FlatBox;
33//! use nn::*;
34//!
35//! fn write_to_memory<T: Copy>(mem: &mut FlatBox, data: &[T]) {
36//!     let mut mem_buffer = mem.as_mut_slice::<T>();
37//!     for (index, datum) in data.iter().enumerate() {
38//!         mem_buffer[index] = *datum;
39//!     }
40//! }
41//!
42//! use crate::co::frameworks::cuda::get_cuda_backend;
43//! pub fn main() {
44//!     // Initialize a CUDA Backend.
45//!     // Usually you would not use CUDA but let Coaster pick what is available on the machine.
46//!     let backend = get_cuda_backend();
47//!
48//!     // Initialize two SharedTensors.
49//!     let mut x = SharedTensor::<f32>::new(&(1, 1, 3));
50//!     let mut result = SharedTensor::<f32>::new(&(1, 1, 3));
51//!     // Fill `x` with some data.
52//!     let payload: &[f32] = &::std::iter::repeat(1f32).take(x.capacity()).collect::<Vec<f32>>();
53//!     let native = Native::new();
54//!     let cpu = native.new_device(native.hardwares()).unwrap();
55//!     write_to_memory(x.write_only(&cpu).unwrap(), payload); // Write to native host memory.
56//!     // Run the sigmoid operation, provided by the NN Plugin, on your CUDA enabled GPU.
57//!     backend.sigmoid(&mut x, &mut result).unwrap();
58//!     // See the result.
59//!     println!("{:?}", result.read(&cpu).unwrap().as_slice::<f64>());
60//! }
61//! # }
62//! # #[cfg(not(feature = "cuda"))]
63//! # mod cuda {
64//! # pub fn main() {}
65//! # }
66//! #
67//! # fn main() {
68//! #     if cfg!(feature = "cuda") {
69//! #         cuda::main();
70//! #    }
71//! # }
72//! ```
73//!
74//! ## Provided Operations
75//!
76//! This Plugins provides the following operations. If not denoted otherwise, this means forward and backward
77//! A `-` means not yet implemented.
78//!
79
80//! | Operation            | CUDA              | OpenCL    | Native    |
81//! |---                   |---                |---        |---        |
82//! | Sigmoid              | cuDNN v5 or later | -         | Rust      |
83//! | SigmoidPointwise     | cuDNN v5 or later | -         | Rust      |
84//! | ReLU                 | cuDNN v5 or later | -         | Rust      |
85//! | ReLUPointwise        | cuDNN v5 or later | -         | Rust      |
86//! | Tanh                 | cuDNN v5 or later | -         | Rust      |
87//! | TanhPointwise        | cuDNN v5 or later | -         | Rust      |
88//! |                      |                   |           |           |
89//! | Normalization (LRN)  | cuDNN v5 or later | -         | -         |
90//! |                      |                   |           |           |
91//! | Dropout              | cuDNN v5 or later | -         | Rust      |
92//! |                      |                   |           |           |
93//! | Convolution          | cuDNN v5 or later | -         | Rust(fwd) |
94//! |                      |                   |           |           |
95//! | Softmax              | cuDNN v5 or later | -         | Rust      |
96//! | LogSoftmax           | cuDNN v5 or later | -         | Rust      |
97//! |                      |                   |           |           |
98//! | Pooling Max          | cuDNN v5 or later | -         | Rust(fwd) |
99//! | Pooling Avg          | cuDNN v5 or later | -         | -         |
100//!
101//! [coaster]: https://github.com/spearow/coaster
102//! [coaster-docs]: https://spearow.github.io/coaster
103//! [blas-source]: https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms
104#![cfg_attr(feature = "unstable", feature(test))]
105#![allow(dead_code)]
106#![deny(
107    unused_crate_dependencies,
108    clippy::missing_docs,
109    clippy::missing_debug_implementations,
110    clippy::missing_copy_implementations,
111    clippy::trivial_casts,
112    clippy::trivial_numeric_casts,
113    clippy::unsafe_code,
114    clippy::unused_import_braces,
115    clippy::unused_qualifications,
116    clippy::complexity
117)]
118
119pub use crate::plugin::*;
120
121#[cfg(feature = "cuda")]
122use rcudnn as cudnn;
123
124pub(crate) use coaster as co;
125
126use log as _;
127
128pub mod frameworks;
129mod plugin;
130
131#[cfg(test)]
132mod tests;
coaster_nn/lib.rs

coaster_nn/
lib.rs
