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
Types around a convolution, see also https://en.wikipedia.org/wiki/Convolution.
Traits from the
num crate which are used inside basic_dsp and extensions to those traits.This mod contains a definition for window functions and provides implementations for a
few standard windows. See the
WindowFunction type for more information.Structs
A 1xN (one times N elements) or Nx1 data vector as used for most digital signal processing
(DSP) operations.
A buffer which gets initalized with a data storage type and then always keeps that.
Buffer borrow type for
SingleBuffer.Holds parameters which specify how multiple cores are used
to execute an operation.
This type can be used everytime the API asks for a buffer to disable any buffering.
Buffer borrow type for
NoBuffer.Buffer borrow type for
NoTradeBufferBurrow.A buffer which stores a single vector and never shrinks.
Buffer borrow type for
SingleBuffer.Statistics about numeric data
Holds meta data about a type.
Enums
The domain of a data vector
Enumeration of all error reasons
An option which defines how a vector should be padded
Constants
The maximum
len for any of the *split methods.Traits
Recommended to be only used with the CPU feature flags
sse or avx.A buffer which can be used by other types. Types will call buffers to create new arrays.
A buffer may can implement any buffering strategy.
A “slice-like” type which also allows to
Like
std::ops::Index
but with a different method name so that it can be used to implement an additional range
accessor for complex data.Like
std::ops::IndexMut
but with a different method name so that it can be used to implement a additional range
accessor for complex data.Trait for types containing complex data.
Operations on complex types.
Defines getters to get real data from complex types.
Defines setters to create complex data from real data.
Defines transformations from complex to real number space.
Defines transformations from complex to real number space.
Provides a convolution operations.
Provides a convolution operation for types which at some point are slice based.
This trait allows to transform an argument so that it can be used for cross correlation. Refer to the description of
CrossCorrelationOps for more details.Cross-correlation of data vectors. See also https://en.wikipedia.org/wiki/Cross-correlation.
A trait to calculate the diff (1st derivative in a discrete number space) or cumulative sum
(integral in a discrete number space).
Domain (time or frequency) information.
An operation which multiplies each vector element with a constant
Elementary algebra on types: addition, subtraction, multiplication and division
Elementary algebra on types where the argument might contain less data points than
self.Like
std::ops::Index
but with a different method name so that it can be used to implement an additional range
accessor for float data.Like
std::ops::IndexMut
but with a different method name so that it can be used to implement a additional range
accessor for float data.Trait for types containing frequency domain data.
Defines all operations which are valid on
DataVecs containing frequency domain data.Provides a frequency response multiplication operations.
Defines all operations which are valid on
DataVecs containing frequency domain data.Retrieves the underlying storage from a vector.
Retrieves the underlying storage from a vector. Returned value will always hold floating point numbers.
Gets the meta data of a type. This can be used to create a new type with the same
meta data.
A trait to insert zeros into the data at some specified positions.
A trait to insert zeros into the data at some specified positions. A buffer is used
for types which can’t be resized and/or to speed up the calculation.
Conversion from two instances of a generic data type into a dsp vector with complex data.
Provides interpolation operations for real and complex data vectors.
Operations which allow to iterate over the vector and to derive results.
Operations which allow to iterate over the vector and to derive results
or to change the vector.
Merges several pieces of equal size into one data chunk.
A trait which provides information about number space and domain.
Operations on real types.
Number space (real or complex) information.
An operation which adds a constant to each vector element
Expresses at compile time that two classes could potentially represent the same number space or domain.
Roots, powers, exponentials and logarithms.
An operation which multiplies each vector element with a constant
Offers the same functionality as the
StatisticsOps trait but
the statistics are calculated in a more precise (and slower) way.Offers the same functionality as the
StatisticsOps trait but
the statistics are calculated in a more precise (and slower) way.A trait for statistics which allows to add new values in a way so that the numerical
uncertainty has less impact on the final results.
Offers the same functionality as the
SumOps trait but
the sums are calculated in a more precise (and slower) way.Provides interpolation operations which are only applicable for real data vectors.
Trait for types containing real data.
Operations on real types.
Defines transformations from real to complex number space.
Defines transformations from real to complex number space.
This trait allows to change a data type and performs the Conversion
without any checks.
RededicateOps provides the same functionality
but performs runtime checks to avoid that data is interpreted the wrong
way.This trait allows to change a data type. The operations will
convert a type to a different one and set
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.This trait allows to change a data type. The operations will
convert a type to a different one and set
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.This trait allows to reorganize the data by changing positions of the individual elements.
A trait for storage types which are known to have the capability to increase their capacity.
Operations to resize a data type.
Operations to resize a data type.
An operation which multiplies each vector element with a constant
Splits the data into several smaller pieces of equal size.
This trait offers operations to calculate statistics about the data in a type.
This trait offers operations to calculate statistics about the data in a type.
Operations on statistics.
Offers operations to calculate the sum or the sum of squares.
Defines all operations which are valid on
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.Defines all operations which are valid on
DataVecs containing real time domain data.Trait for types containing time domain data.
Defines all operations which are valid on
DataVecs containing time domain data.Defines all operations which are valid on
DataVecs containing time domain data.Specifies what the the result is if a type is transformed to complex numbers.
Conversion from a generic data type into a dsp vector with complex data.
Conversion from a generic data type into a dsp vector with complex data.
Conversion from a generic data type into a dsp vector which tracks
its meta information (domain and number space)
only at runtime. See
ToRealVector and
ToComplexVector for alternatives which track most of the meta data
with the type system and therefore avoid runtime errors.Conversion from a generic data type into a dsp vector which tracks
its meta information (domain and number space)
only at runtime. See
ToRealVector and
ToComplexVector for alternatives which track most of the meta data
with the type system and therefore avoid runtime errors.Specifies what the the result is if a type is transformed to frequency domain.
Specifies what the the result is if a type is transformed to real numbers.
Specifies what the the result is if a type is transformed to real numbers in time domain.
Conversion from a generic data type into a dsp vector with real data.
Conversion from a generic data type into a dsp vector with real data.
A trait to convert a type into a slice.
A trait to convert a type into a mutable slice.
Specifies what the the result is if a type is transformed to time domain.
Trigonometry methods.
A trait for vector types.
Functions
Prints debug information about the calibration. The calibration determines when the library
will start to spawn threads. If a calibration hasn’t been performed yet
than calling this function will trigger the calibration.
Type Definitions
A vector with complex numbers in frequency domain.
A vector with complex numbers in frequency domain.
A vector with complex numbers in frequency domain.
A vector with complex numbers in frequency domain.
A vector with complex numbers in frequency domain.
A vector with complex numbers in time domain.
A vector with complex numbers in time domain.
A vector with complex numbers in time domain.
A vector with complex numbers in time domain.
A vector with complex numbers in time domain.
A vector with no information about number space or domain at compile time.
A vector with no information about number space or domain at compile time.
A vector with no information about number space or domain at compile time.
A vector with no information about number space or domain at compile time.
A vector with no information about number space or domain at compile time.
A vector with real numbers in frequency domain.
A vector with real numbers in frequency domain.
A vector with real numbers in frequency domain.
A vector with real numbers in frequency domain.
A vector with real numbers in frequency domain.
A vector with real numbers in time domain.
A vector with real numbers in time domain.
A vector with real numbers in time domain.
A vector with real numbers in time domain.
A vector with real numbers in time domain.
Scalar result or a reason in case of an error.
Alias for a vector of any statistical information.
Result for operations which transform a type (most commonly the type is a vector).
On success the transformed type is returned.
On failure it contains an error reason and the original type with with invalid data
which still can be used in order to avoid memory allocation.
Void/nothing in case of success or a reason in case of an error.