Struct ocl_convolution::Convolution

pub struct Convolution<T: ConvElement>(_);

Convolution without pinned memory.

Methods

impl Convolution<f32>

pub fn f32(size: usize) -> Result<ConvolutionBuilder<f32>>

Creates a new floating-point convolution builder. size determines the filter size and should be odd (1, 3, 5, ...).

Panics

Panics if the filter size is even.

impl Convolution<i8>

Quantized convolution over signed 8-bit integers.

Due to use of i8 inputs, computations are performed much faster than on f32 inputs (the difference manifests most on the specialized hardware, but it is seen in this OpenCL-powered implementation as well).

Connection to real-value convolution

Quantized convolution mirrors real-valued convolution in which i8 elements of the signal, filter and output tensors represent real-valued numbers with the following mapping:

let scale: f32 = // ...
let bias: i32 = // ...
|x: i8| -> f32 { scale * (i32::from(x) - bias) as f32 }

scale and bias may differ for different tensors; these params are usually determined by profiling the corresponding convolutional neural network (see e.g. this paper).

Denote these quantiation params for tensor T as T.scale and T.bias. Denote S the signal, F the filter, O the output. Convolution parameters should be set as follows:

I8Params field	Value
signal_bias	-S.bias
filter_bias	-F.bias
output_bias	O.bias
scale	S.scale * F.scale / O.scale

scale is represented as a fixed-point number with bit_shift binary digits after the point. Note that filter biases B are not transformed during the computation.

Computing convolution

Suppose S is the signal and F is the filter tensor; both contain i8 values. The computation is performed as follows:

1. Unbias the signal: S := S + params.signal_bias.
2. Unbias the filters: F := F + params.filter_bias.
3. Compute "standard" convolution output O := S (*) F using i32 precision.
4. Upscale each number in the output: O := O * params.scale.
5. If there is filter bias B provided, apply bias to the output per each output channel: O[f, ..] := O[f, ..] + B[f].
6. Downscale the output: O := round(O / 2**self.bit_shift), where round() works as floating-point rounding with the default mode (round to nearest, ties to even).
7. Apply output bias: O := O + params.output_bias.
8. Saturate output to i8 range.

pub fn i8(size: usize) -> Result<ConvolutionBuilder<i8>>

Creates a new i8 convolution builder. size determines the filter size and should be odd (1, 3, 5, ...).

Panics

Panics if the filter size is even.

impl<T: ConvElement> Convolution<T>

pub fn size(&self) -> usize

Spatial size of the convolution.

pub fn params(&self) -> &T::Params

Returns general parameters of the convolution.

pub fn set_params(&mut self, params: T::Params) -> Result<()>

Sets convolution parameters.

pub fn with_filters<'a>(
    self,
    filters: impl Into<ArrayView4<'a, T>>
) -> Result<FiltersConvolution<T>>

Returns the convolution with pinned filter memory.

Parameters

• filters should have MxK_HxK_WxC layout, where M is the number of filters, K_H and K_W are spatial dimensions of a filter, C is the number of input channels.

pub fn with_biased_filters<'a>(
    self,
    filters: impl Into<ArrayView4<'a, T>>,
    filter_biases: &[T::Acc]
) -> Result<FiltersConvolution<T>>

Returns the convolution with pinned filter / filter bias memory.

pub fn compute<'a>(
    &self,
    signal: FeatureMap<T>,
    filters: impl Into<ArrayView4<'a, T>>
) -> Result<Array4<T>>

Performs convolution on the provided signal and filters.

Parameters

• filters should have MxK_HxK_WxC layout, where M is the number of filters, K_H and K_W are spatial dimensions of a filter, C is the number of input channels.

Return value

The output will have the same layout as signal. An error means something wrong with OpenCL.

Panics

• The method will panic if filters do not have expected spatial dimensions, i.e., self.size() x self.size().
• Likewise, the method will panic if the number of input channels differs from number of channels in filters.

pub fn compute_with_biases<'a>(
    &self,
    signal: FeatureMap<T>,
    filters: impl Into<ArrayView4<'a, T>>,
    filter_biases: &[T::Acc]
) -> Result<Array4<T>>

Performs convolution on the provided signal and filters, with the output offset by the provided per-filter biases.

Parameters, return value and panics are generally the same as for compute().

Trait Implementations

impl<T: Debug + ConvElement> Debug for Convolution<T>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.