Crate basic_dsp_vector
source · [−]Expand description
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:
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 vectors are meant to integrate well with other types and so they can for example be converted from and to a Rust standard vector:
let mut dsp_vec = vec![0.0; 1000].to_real_time_vec();
let mut buffer = SingleBuffer::new();
dsp_vec.interpolatei(&mut buffer, &RaisedCosineFunction::new(0.35), 2).unwrap();
let vec: Vec<f64> = dsp_vec.into();
assert_eq!(vec.len(), 2000);
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:
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.
Modules
num
crate which are used inside basic_dsp
and extensions to those traits.WindowFunction
type for more information.Structs
SingleBuffer
.NoBuffer
.NoTradeBufferBurrow
.SingleBuffer
.Enums
Constants
len
for any of the *split
methods.Traits
sse
or avx
.std::ops::Index
but with a different method name so that it can be used to implement an additional range
accessor for complex data.std::ops::IndexMut
but with a different method name so that it can be used to implement a additional range
accessor for complex data.CrossCorrelationOps
for more details.self
.std::ops::Index
but with a different method name so that it can be used to implement an additional range
accessor for float data.std::ops::IndexMut
but with a different method name so that it can be used to implement a additional range
accessor for float data.DataVecs
containing frequency domain data.DataVecs
containing frequency domain data.StatisticsOps
trait but
the statistics are calculated in a more precise (and slower) way.StatisticsOps
trait but
the statistics are calculated in a more precise (and slower) way.SumOps
trait but
the sums are calculated in a more precise (and slower) way.RededicateOps
provides the same functionality
but performs runtime checks to avoid that data is interpreted the wrong
way.self.len()
to zero.
However self.allocated_len()
will remain unchanged. The use case for this
is to allow to reuse the memory of a vector for different operations.self.len()
to zero.
However self.allocated_len()
will remain unchanged. The use case for this
is to allow to reuse the memory of a vector for different operations.DataVecs
containing frequency domain data and
the data is assumed to half of complex conjugate symmetric spectrum round 0 Hz where
the 0 Hz element itself is real.DataVecs
containing real time domain data.DataVecs
containing time domain data.DataVecs
containing time domain data.ToRealVector
and
ToComplexVector
for alternatives which track most of the meta data
with the type system and therefore avoid runtime errors.ToRealVector
and
ToComplexVector
for alternatives which track most of the meta data
with the type system and therefore avoid runtime errors.