Basic digital signal processing (DSP) operations
Digital signal processing based on real or complex vectors in time or frequency domain. Vectors are expected to typically have a size which is at least in the order of magnitude of a couple of thousand elements. This crate tries to balance between a clear API and performance in terms of processing speed.
Take this example:
# extern crate num_complex;
# extern crate basic_dsp_vector;
# use basic_dsp_vector::*;
# fn main() {
let mut vector1 = vec!(1.0, 2.0).to_real_time_vec();
let vector2 = vec!(10.0, 11.0).to_real_time_vec();
vector1.add(&vector2).expect("Ignoring error handling in examples");
# }
If vector2 would be a complex or frequency vector then this won't compile. The type mismatch
indicates that a conversation is missing and that this might be a programming mistake. This lib uses
the Rust type system to catch such errors.
DSP algorithms are often executed in loops. If you work with large vectors you typically try to avoid allocating buffers in every iteration. Preallocating buffers is a common practice to safe a little time with every iteration later on, but also to avoid heap fragmentation. At the same time it's a tedious task to calculate the right buffer sizes for all operations. As an attempt to provide a more convenient solution buffer types exist which don't preallocate, but store temporary memory segments so that they can be reused in the next iteration. Here is an example:
# use std::f32;
# use basic_dsp_vector::*;
let vector = vec!(1.0, 0.0, -0.5, 0.8660254, -0.5, -0.8660254).to_complex_time_vec();
let mut buffer = SingleBuffer::new();
let _ = vector.fft(&mut buffer);
The vector types don't distinguish between the shapes 1xN or Nx1. This is a difference to other
conventions such as in MATLAB or GNU Octave.
The reason for this decision is that most operations are only defined if the shape of the
vector matches. So it appears to be more practical and clearer to implement the few operations
where the arguments can be of different shapes as seperate methods. The methods mul and dot_product
are one example for this.
The trait definitions in this lib can look complex and might be overwhelming at the beginning.
There is a wide range of DSP vectors, e.g. a slice can be DSP vector, a boxed array can be a DSP vector,
a standard vector can be a DSP vector and so on. This lib tries to work with all of that and tries
to allow all those different DSP vector types to work together. The price for this flexibility is a more complex
trait definition. As a mental model, this is what the traits are specifiying:
Whenever you have a complex vector in time domain, it's binary operations will work with all other
complex vectors in time domain, but not with real valued vectors or frequency domain vectors.
And the type GenDspVec serves as wild card at compile time since it defers all checks to run time.