Crate wavegen

Expand description

Rust waveform generator, with no_std support.

Quickstart

use wavegen::{wf, sine, dc_bias, sawtooth};

// Define a Waveform with 200Hz sampling rate and three function components,
// choosing f32 as the output type:
let waveform = wf!(f32, 200., sine!(50., 10.), sawtooth!(20.), dc_bias!(-5.));

// Use Waveform as an infinite iterator:
let two_seconds_of_samples: Vec<f32> = waveform.iter().take(400).collect();

Look into macros section for a complete list of defined periodic functions and their constructors.

Custom periodic functions

Supported, of course. Just define your custom function as Box<Fn(f64) -> f64> and use it with Waveform.

use wavegen::{wf, PeriodicFunction};

let waveform = wf!(f64, 100.0, PeriodicFunction::custom(|x| x % 2.0));

As Waveform can be composed of multiple components, it is possible for it to overflow during samples collection. If overflow occurs, the sample’s value will be clamped to the largest possible representation of sample’s type.

That means +/- Inf for floating point types, and MAX/MIN for integers.

use wavegen::{Waveform, dc_bias};

let wf = Waveform::<f64>::with_components(100.0, vec![dc_bias![f32::MAX], dc_bias![f32::MAX]]);
let sample = wf.iter().take(1).collect::<Vec<_>>()[0];

assert_eq!(sample, f64::INFINITY);

use wavegen::{Waveform, dc_bias};

let wf = Waveform::<i32>::with_components(100.0, vec![dc_bias![f32::MAX], dc_bias![f32::MAX]]);
let sample = wf.iter().take(1).collect::<Vec<_>>()[0];

assert_eq!(sample, i32::MAX);

Calculation precision

By default, all calculations in Waveform use single floating point precision f32. This can be set to f64 if needed, possibly in case of very high frequencies. To do so, set the P type parameter to f64:

let double_precision_waveform = wavegen::Waveform::<f64, f64>::new(1e100);

Iterator infinity

WaveformIterator is a mostly infinite iterator, with one exception:

The WaveformIterator::next method can return None in some rare cases if it is not able to convert the inner sample type f64 into the target sample type.

f64::NAN cannot be represented as i32:

use wavegen::{Waveform, PeriodicFunction};

let mut wf = Waveform::<i32, f64>::new(100.0);
wf.add_component(PeriodicFunction::dc_bias(f64::NAN));

assert_eq!(None, wf.iter().next())

This however is fine, as f64::NAN can be represented as f32::NAN:

use wavegen::{Waveform, PeriodicFunction};

let mut wf = Waveform::<f32, f64>::new(100.0);
wf.add_component(PeriodicFunction::dc_bias(f64::NAN));

assert!(wf.iter().next().unwrap().is_nan())

It is probably a good practice to sanitize the parameters of the periodic function before it is constructed.

Note about Nyquist-Shannon rule enforcement

As a rule of thumb in signal processing, the sampling frequency should be at least 2 times bigger than the highest frequency of sampled continous signal.

This lib will not enforce the Nyquist-Shannon rule on the waveforms you create, therefore abominations like this are possible (altough not recommended):

use wavegen::{Waveform, sine};

// 100 Hz sampling of 80 Hz sine... will not yield realistic results.
let wf = Waveform::<f32>::with_components(100.0, vec![sine!(80.)]);

As it is often a case, it is you, the programmer, who’s left in charge of making sure the input data makes sense.