Trait basic_dsp::ComplexVectorOps [−] [src]

pub trait ComplexVectorOps<T>: DataVector<T> where T: RealNumber {
    type RealPartner;
    fn complex_data(&self) -> &[Complex<T>];
    fn complex_offset(self, offset: Complex<T>) -> VecResult<Self>;
    fn complex_scale(self, factor: Complex<T>) -> VecResult<Self>;
    fn multiply_complex_exponential(self, a: T, b: T) -> VecResult<Self>;
    fn magnitude(self) -> VecResult<Self::RealPartner>;
    fn get_magnitude(&self, destination: &mut Self::RealPartner) -> VoidResult;
    fn magnitude_squared(self) -> VecResult<Self::RealPartner>;
    fn conj(self) -> VecResult<Self>;
    fn to_real(self) -> VecResult<Self::RealPartner>;
    fn to_imag(self) -> VecResult<Self::RealPartner>;
    fn get_real(&self, destination: &mut Self::RealPartner) -> VoidResult;
    fn get_imag(&self, destination: &mut Self::RealPartner) -> VoidResult;
    fn phase(self) -> VecResult<Self::RealPartner>;
    fn get_phase(&self, destination: &mut Self::RealPartner) -> VoidResult;
    fn complex_dot_product(&self, factor: &Self) -> ScalarResult<Complex<T>>;
    fn complex_statistics(&self) -> Statistics<Complex<T>>;
    fn complex_statistics_splitted(&self, len: usize) -> Vec<Statistics<Complex<T>>>;
    fn complex_sum(&self) -> Complex<T>;
    fn complex_sum_sq(&self) -> Complex<T>;
    fn get_real_imag(&self, real: &mut Self::RealPartner, imag: &mut Self::RealPartner) -> VoidResult;
    fn get_mag_phase(&self, mag: &mut Self::RealPartner, phase: &mut Self::RealPartner) -> VoidResult;
    fn set_real_imag(self, real: &Self::RealPartner, imag: &Self::RealPartner) -> VecResult<Self>;
    fn set_mag_phase(self, mag: &Self::RealPartner, phase: &Self::RealPartner) -> VecResult<Self>;
    fn map_inplace_complex<A, F>(self, argument: A, map: F) -> VecResult<Self> where A: Sync + Copy + Send, F: Fn(Complex<T>, usize, A) -> Complex<T> + 'static + Sync;
    fn map_aggregate_complex<A, FMap, FAggr, R>(&self, argument: A, map: FMap, aggregate: FAggr) -> ScalarResult<R> where A: Sync + Copy + Send, FMap: Fn(Complex<T>, usize, A) -> R + 'static + Sync, FAggr: Fn(R, R) -> R + 'static + Sync + Send, R: Send;
}

Defines all operations which are valid on DataVectors containing complex data.

Failures

All operations in this trait fail with VectorMustBeComplex if the vector isn't in the complex number space.

Associated Types

type RealPartner

Required Methods

fn complex_data(&self) -> &[Complex<T>]

Gets self.data() as complex array.

fn complex_offset(self, offset: Complex<T>) -> VecResult<Self>

Adds a scalar to the vector. See also OffsetOps.

Example

use basic_dsp::{ComplexTimeVector32, ComplexVectorOps, DataVector};
use num::complex::Complex32;
let vector = ComplexTimeVector32::from_interleaved(&[1.0, 2.0, 3.0, 4.0]);
let result = vector.complex_offset(Complex32::new(-1.0, 2.0)).expect("Ignoring error handling in examples");
assert_eq!([0.0, 4.0, 2.0, 6.0], result.data());

fn complex_scale(self, factor: Complex<T>) -> VecResult<Self>

Multiplies the vector with a scalar. See also ScaleOps.

Example

use basic_dsp::{ComplexTimeVector32, ComplexVectorOps, DataVector};
use num::complex::Complex32;
let vector = ComplexTimeVector32::from_interleaved(&[1.0, 2.0, 3.0, 4.0]);
let result = vector.complex_scale(Complex32::new(-1.0, 2.0)).expect("Ignoring error handling in examples");
assert_eq!([-5.0, 0.0, -11.0, 2.0], result.data());

fn multiply_complex_exponential(self, a: T, b: T) -> VecResult<Self>

Multiplies each vector element with exp(j*(a*idx*self.delta() + b)) where a and b are arguments and idx is the index of the data points in the vector ranging from 0 to self.points() - 1. j is the imaginary number and exp the exponential function.

This method can be used to perform a frequency shift in time domain.

Example

use basic_dsp::{ComplexTimeVector32, ComplexVectorOps, DataVector};
let vector = ComplexTimeVector32::from_interleaved(&[1.0, 2.0, 3.0, 4.0]);
let result = vector.multiply_complex_exponential(2.0, 3.0).expect("Ignoring error handling in examples");
let expected = [-1.2722325, -1.838865, 4.6866837, -1.7421241];
let result = result.data();
for i in 0..expected.len() {
    assert!((result[i] - expected[i]).abs() < 1e-4);   
}

fn magnitude(self) -> VecResult<Self::RealPartner>

Gets the absolute value, magnitude or norm of all vector elements.

Example

use basic_dsp::{ComplexTimeVector32, ComplexVectorOps, DataVector};
use num::complex::Complex32;
let vector = ComplexTimeVector32::from_interleaved(&[3.0, -4.0, -3.0, 4.0]);
let result = vector.magnitude().expect("Ignoring error handling in examples");
assert_eq!([5.0, 5.0], result.data());

fn get_magnitude(&self, destination: &mut Self::RealPartner) -> VoidResult

Copies the absolute value or magnitude of all vector elements into the given target vector.

Example

use basic_dsp::{ComplexTimeVector32, RealTimeVector32, ComplexVectorOps, DataVector};
let vector = ComplexTimeVector32::from_interleaved(&[3.0, -4.0, -3.0, 4.0]);
let mut result = RealTimeVector32::from_array(&[0.0]);
vector.get_magnitude(&mut result).expect("Ignoring error handling in examples");
assert_eq!([5.0, 5.0], result.data());

fn magnitude_squared(self) -> VecResult<Self::RealPartner>

Gets the square root of the absolute value of all vector elements.

Example

use basic_dsp::{ComplexTimeVector32, ComplexVectorOps, DataVector};
use num::complex::Complex32;
let vector = ComplexTimeVector32::from_interleaved(&[3.0, -4.0, -3.0, 4.0]);
let result = vector.magnitude_squared().expect("Ignoring error handling in examples");
assert_eq!([25.0, 25.0], result.data());

fn conj(self) -> VecResult<Self>

Calculates the complex conjugate of the vector.

Example

use basic_dsp::{ComplexTimeVector32, ComplexVectorOps, DataVector};
let vector = ComplexTimeVector32::from_interleaved(&[1.0, 2.0, 3.0, 4.0]);
let result = vector.conj().expect("Ignoring error handling in examples");
assert_eq!([1.0, -2.0, 3.0, -4.0], result.data());

fn to_real(self) -> VecResult<Self::RealPartner>

Gets all real elements.

Example

use basic_dsp::{ComplexTimeVector32, ComplexVectorOps, DataVector};
let vector = ComplexTimeVector32::from_interleaved(&[1.0, 2.0, 3.0, 4.0]);
let result = vector.to_real().expect("Ignoring error handling in examples");
assert_eq!([1.0, 3.0], result.data());

fn to_imag(self) -> VecResult<Self::RealPartner>

Gets all imag elements.

Example

use basic_dsp::{ComplexTimeVector32, ComplexVectorOps, DataVector};
let vector = ComplexTimeVector32::from_interleaved(&[1.0, 2.0, 3.0, 4.0]);
let result = vector.to_imag().expect("Ignoring error handling in examples");
assert_eq!([2.0, 4.0], result.data());

fn get_real(&self, destination: &mut Self::RealPartner) -> VoidResult

Copies all real elements into the given vector.

Example

use basic_dsp::{RealTimeVector32, ComplexTimeVector32, ComplexVectorOps, DataVector};
let mut result = RealTimeVector32::from_array(&[0.0, 0.0]);
let vector = ComplexTimeVector32::from_real_imag(&[1.0, 3.0], &[2.0, 4.0]);
vector.get_real(&mut result).expect("Ignoring error handling in examples");
assert_eq!([1.0, 3.0], result.data());

fn get_imag(&self, destination: &mut Self::RealPartner) -> VoidResult

Copies all imag elements into the given vector.

Example

use basic_dsp::{RealTimeVector32, ComplexTimeVector32, ComplexVectorOps, DataVector};
let mut result = RealTimeVector32::from_array(&[0.0, 0.0]);
let vector = ComplexTimeVector32::from_real_imag(&[1.0, 3.0], &[2.0, 4.0]);
vector.get_imag(&mut result).expect("Ignoring error handling in examples");
assert_eq!([2.0, 4.0], result.data());

fn phase(self) -> VecResult<Self::RealPartner>

Gets the phase of all elements in [rad].

Example

use basic_dsp::{ComplexTimeVector32, ComplexVectorOps, DataVector};
let vector = ComplexTimeVector32::from_interleaved(&[1.0, 0.0, 0.0, 4.0, -2.0, 0.0, 0.0, -3.0, 1.0, 1.0]);
let result = vector.phase().expect("Ignoring error handling in examples");
assert_eq!([0.0, 1.5707964, 3.1415927, -1.5707964, 0.7853982], result.data());

fn get_phase(&self, destination: &mut Self::RealPartner) -> VoidResult

Copies the phase of all elements in [rad] into the given vector.

Example

use basic_dsp::{RealTimeVector32, ComplexTimeVector32, ComplexVectorOps, DataVector};
let mut result = RealTimeVector32::from_array(&[0.0, 0.0]);
let vector = ComplexTimeVector32::from_interleaved(&[1.0, 0.0, 0.0, 4.0, -2.0, 0.0, 0.0, -3.0, 1.0, 1.0]);
vector.get_phase(&mut result).expect("Ignoring error handling in examples");
assert_eq!([0.0, 1.5707964, 3.1415927, -1.5707964, 0.7853982], result.data());

fn complex_dot_product(&self, factor: &Self) -> ScalarResult<Complex<T>>

Calculates the dot product of self and factor. Self and factor remain unchanged. See also DotProductOps.

Failures

VecResult may report the following ErrorReason members:

  1. VectorMetaDataMustAgree: self and factor must be in the same domain and number space

Example

use basic_dsp::{ComplexTimeVector32, ComplexVectorOps};
let vector1 = ComplexTimeVector32::from_interleaved(&[9.0, 2.0, 7.0, 1.0]);
let vector2 = ComplexTimeVector32::from_interleaved(&[4.0, 0.0, 10.0, 0.0]);
let result = vector1.complex_dot_product(&vector2).expect("Ignoring error handling in examples");
assert_eq!(Complex32::new(106.0, 18.0), result);
}

fn complex_statistics(&self) -> Statistics<Complex<T>>

Calculates the statistics of the data contained in the vector. See also StatisticsOps.

Example

use basic_dsp::{ComplexTimeVector32, ComplexVectorOps};
let vector = ComplexTimeVector32::from_interleaved(&[1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
let result = vector.complex_statistics();
assert_eq!(result.sum, Complex32::new(9.0, 12.0));
assert_eq!(result.count, 3);
assert_eq!(result.average, Complex32::new(3.0, 4.0));
assert!((result.rms - Complex32::new(3.4027193, 4.3102784)).norm() < 1e-4);
assert_eq!(result.min, Complex32::new(1.0, 2.0));
assert_eq!(result.min_index, 0);
assert_eq!(result.max, Complex32::new(5.0, 6.0));
assert_eq!(result.max_index, 2);
}

fn complex_statistics_splitted(&self, len: usize) -> Vec<Statistics<Complex<T>>>

Calculates the statistics of the data contained in the vector as if the vector would have been split into len pieces. self.len should be dividable by len without a remainder, but this isn't enforced by the implementation. See also StatisticsOps.

Example

use basic_dsp::{ComplexTimeVector32, ComplexVectorOps};
let vector = ComplexTimeVector32::from_interleaved(&[1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]);
let result = vector.complex_statistics_splitted(2);
assert_eq!(result[0].sum, Complex32::new(6.0, 8.0));
assert_eq!(result[1].sum, Complex32::new(10.0, 12.0));
}

fn complex_sum(&self) -> Complex<T>

Calculates the sum of the data contained in the vector. See also StatisticsOps.

Example

use basic_dsp::{ComplexTimeVector32, ComplexVectorOps};
let vector = ComplexTimeVector32::from_interleaved(&[1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
let result = vector.complex_sum();
assert_eq!(result, Complex32::new(9.0, 12.0));
}

fn complex_sum_sq(&self) -> Complex<T>

Calculates the sum of the data contained in the vector. See also StatisticsOps.

Example

use basic_dsp::{ComplexTimeVector32, ComplexVectorOps};
let vector = ComplexTimeVector32::from_interleaved(&[1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
let result = vector.complex_sum_sq();
assert_eq!(result, Complex32::new(-21.0, 88.0));
}

fn get_real_imag(&self, real: &mut Self::RealPartner, imag: &mut Self::RealPartner) -> VoidResult

Gets the real and imaginary parts and stores them in the given vectors. See also get_phase and get_complex_abs for further information.

fn get_mag_phase(&self, mag: &mut Self::RealPartner, phase: &mut Self::RealPartner) -> VoidResult

Gets the magnitude and phase and stores them in the given vectors. See also get_real and get_imag for further information.

fn set_real_imag(self, real: &Self::RealPartner, imag: &Self::RealPartner) -> VecResult<Self>

Overrides the self vectors data with the real and imaginary data in the given vectors. real and imag must have the same size.

fn set_mag_phase(self, mag: &Self::RealPartner, phase: &Self::RealPartner) -> VecResult<Self>

Overrides the self vectors data with the magnitude and phase data in the given vectors. Note that self vector will immediately convert the data into a real and imaginary representation of the complex numbers which is its default format. mag and phase must have the same size.

fn map_inplace_complex<A, F>(self, argument: A, map: F) -> VecResult<Self> where A: Sync + Copy + Send, F: Fn(Complex<T>, usize, A) -> Complex<T> + 'static + Sync

Transforms all vector elements using the function map.

Example

use basic_dsp::*;
let a = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0];
let c = ComplexTimeVector32::from_interleaved(&a);
let r = c.map_inplace_complex((), |v, i, _|v * Complex32::new(i as f32, 0.0)).expect("Ignoring error handling in examples");
let expected = [0.0, 0.0, 3.0, 4.0, 10.0, 12.0];
assert_eq!(r.data(), &expected);

fn map_aggregate_complex<A, FMap, FAggr, R>(&self, argument: A, map: FMap, aggregate: FAggr) -> ScalarResult<R> where A: Sync + Copy + Send, FMap: Fn(Complex<T>, usize, A) -> R + 'static + Sync, FAggr: Fn(R, R) -> R + 'static + Sync + Send, R: Send

Transforms all vector elements using the function map and then aggregates all the results with aggregate. aggregate must be a commutativity and associativity; that's because there is no guarantee that the numbers will be aggregated in any deterministic order.

Example

use basic_dsp::*;
let a = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0];
let c = ComplexTimeVector32::from_interleaved(&a);
let r = c.map_aggregate_complex(
     (), 
     |v, i, _|v.re as usize * i, 
     |a,b|a+b).expect("Ignoring error handling in examples");
assert_eq!(r, 13);

Implementors