libosmodsp: Complex vectors math and signal processing

libosmodsp 0.4.0.12-f6f4 Osmocom DSP library

Files | Enumerations | Functions
Complex vectors math and signal processing
Complex vectors

## Files
file | cxvec_math.h
| Osmocom Complex vectors math header.
file | cxvec_math.c
| Osmocom Complex vectors math implementation.

## Enumerations
enum | osmo_cxvec_conv_type { CONV_FULL_SPAN , CONV_OVERLAP_ONLY , CONV_NO_DELAY }
| Various possible types of convolution span. More...
enum | osmo_cxvec_peak_alg { PEAK_WEIGH_WIN , PEAK_WEIGH_WIN_CENTER , PEAK_EARLY_LATE }
| Various possible peak finding algorithms. More...

## Functions
static float | osmo_sinc (float x)
| Unnormalized sinc function. More...
static float | osmo_normsqf (float complex c)
| Squared norm of a given complex. More...
struct osmo_cxvec * | osmo_cxvec_scale (const struct osmo_cxvec *in, float complex scale, struct osmo_cxvec *out)
| Scale a complex vector (multiply by a constant) More...
struct osmo_cxvec * | osmo_cxvec_rotate (const struct osmo_cxvec *in, float rps, struct osmo_cxvec *out)
| Rotate a complex vector (frequency shift) More...
struct osmo_cxvec * | osmo_cxvec_delay (const struct osmo_cxvec *in, float delay, struct osmo_cxvec *out)
| Fractionally delay a vector while maintaining its length. More...
struct osmo_cxvec * | osmo_cxvec_convolve (const struct osmo_cxvec *f, const struct osmo_cxvec *g, enum osmo_cxvec_conv_type type, struct osmo_cxvec *out)
| Convolve two complex vectors. More...
struct osmo_cxvec * | osmo_cxvec_correlate (const struct osmo_cxvec *f, const struct osmo_cxvec *g, int g_corr_step, struct osmo_cxvec *out)
| Cross-correlate two complex vectors. More...
float complex | osmo_cxvec_interpolate_point (const struct osmo_cxvec *cv, float pos)
| Interpolate any fractional position in a vector using sinc filtering. More...
int | osmo_cxvec_peaks_scan (const struct osmo_cxvec *cv, int *peaks_idx, int N)
| Find the index of the N highest energy ( ) peaks. More...
float | osmo_cxvec_peak_energy_find (const struct osmo_cxvec *cv, int win_size, enum osmo_cxvec_peak_alg alg, float complex *peak_val_p)
| Find the maximum energy ( ) peak in a sequence. More...
struct osmo_cxvec * | osmo_cxvec_sig_normalize (const struct osmo_cxvec *sig, int decim, float freq_shift, struct osmo_cxvec *out)
| 'Normalize' an IQ signal and apply decimation/frequency shift More...

## Detailed Description

## Enumeration Type Documentation

## ◆ osmo_cxvec_conv_type

enum osmo_cxvec_conv_type

Various possible types of convolution span.

Enumerator
CONV_FULL_SPAN | Full span (every possible overlap of f onto g)
CONV_OVERLAP_ONLY | Every possible full overlap of f onto g.
CONV_NO_DELAY | Center f sequence on every g sample.

## ◆ osmo_cxvec_peak_alg

enum osmo_cxvec_peak_alg

Various possible peak finding algorithms.

Enumerator
PEAK_WEIGH_WIN | Weigthed position for the max pwr window.
PEAK_WEIGH_WIN_CENTER | Weighted position of the peak centered window.
PEAK_EARLY_LATE | Early-Late balancing around peak.

## Function Documentation

## ◆ osmo_cxvec_convolve()

struct osmo_cxvec * osmo_cxvec_convolve | ( | const struct osmo_cxvec * | f,
|  | const struct osmo_cxvec * | g,
|  | enum osmo_cxvec_conv_type | type,
|  | struct osmo_cxvec * | out
| ) |  |

Convolve two complex vectors.

Parameters

  [in] | f | First input complex vector
  [in] | g | Second input complex vector
  [in] | type | The convolution span type
  [out] | out | Output complex vector

Returns
  The output complex vector (or NULL if error)

The convolution of discrete sequences is defined as :

Altough the mathematical operation is commutative, the constraint of implementation limit this method. Depending on the type of span chosen, it might not be and it's always recommended that 'g' be the longer sequence. It should not be much of a limitation when this methos is used for filtering or pulseshaping : use 'f' as the filter and 'g' as the signal.

The output vector parameter 'out' can be NULL to allocate a new vector. If it's not NULL, it must be long enough to contain the result (length depends on the exact convolution type)

References CONV_FULL_SPAN, CONV_NO_DELAY, CONV_OVERLAP_ONLY, osmo_cxvec::data, osmo_cxvec::flags, osmo_cxvec::len, osmo_cxvec::max_len, and osmo_cxvec_alloc().

Referenced by osmo_cxvec_delay().

## ◆ osmo_cxvec_correlate()

struct osmo_cxvec * osmo_cxvec_correlate | ( | const struct osmo_cxvec * | f,
|  | const struct osmo_cxvec * | g,
|  | int | g_corr_step,
|  | struct osmo_cxvec * | out
| ) |  |

Cross-correlate two complex vectors.

Parameters

  [in] | f | First input complex vector
  [in] | g | Second input complex vector
  [in] | g_corr_step | Allow for oversampling of 'g' compared to 'f'
  [out] | out | Output complex vector

Returns
  The output complex vector (or NULL if error)

The cross-correlation of discrete sequences is defined as :

In this implementation, the output vector will be for every n value between 0 and (g->len - f->len + 1). This assumes that g is the longer sequence and we 'fit' f at every positition inside it.

With the parameter g_corr_step, it's also possible to have a g sequence that is oversampled with regard to f. (if g_corr_step > 1)

The output vector parameter 'out' can be NULL to allocate a new vector. If it's not NULL, it must be long enough to contain the result (i.e. g->len - f->len + 1)

References osmo_cxvec::data, osmo_cxvec::flags, osmo_cxvec::len, osmo_cxvec::max_len, and osmo_cxvec_alloc().

## ◆ osmo_cxvec_delay()

struct osmo_cxvec * osmo_cxvec_delay | ( | const struct osmo_cxvec * | in,
|  | float | delay,
|  | struct osmo_cxvec * | out
| ) |  |

Fractionally delay a vector while maintaining its length.

Parameters

  [in] | in | Input complex vector
  [in] | delay | The fractional delay to apply
  [out] | out | Output complex vector

Returns
  The output complex vector (or NULL if error)

The output always has the same length. Samples pushed out by the delays are lost and new ones filled with zeroes are pushed in.

The output vector parameter 'out' can be NULL to allocate a new vector, or can be equal to the 'in' input vector to perform the transform in-place. If it's different, it must be long enough to contain the result (i.e. in->len)

References CONV_NO_DELAY, osmo_cxvec::data, osmo_cxvec::flags, osmo_cxvec::len, osmo_cxvec::max_len, osmo_cxvec_alloc(), osmo_cxvec_convolve(), osmo_cxvec_free(), osmo_cxvec_init_from_data(), and osmo_sinc().

## ◆ osmo_cxvec_interpolate_point()

float complex osmo_cxvec_interpolate_point | ( | const struct osmo_cxvec * | cv,
|  | float | pos
| ) |  |

Interpolate any fractional position in a vector using sinc filtering.

Parameters

  [in] | cv | Input complex vector
  [in] | pos | Position to interpolate

pos must be >= 0 and < cv->len

References osmo_cxvec::data, osmo_cxvec::flags, osmo_cxvec::len, and osmo_sinc().

Referenced by osmo_cxvec_peak_energy_find().

## ◆ osmo_cxvec_peak_energy_find()

float osmo_cxvec_peak_energy_find | ( | const struct osmo_cxvec * | cv,
|  | int | win_size,
|  | enum osmo_cxvec_peak_alg | alg,
|  | float complex * | peak_val_p
| ) |  |

Find the maximum energy ( ) peak in a sequence.

Parameters

  [in] | cv | Input complex vector
  [in] | win_size | Size of the window (for algorithms using windows)
  [in] | alg | Peak detection algorithm to use
  [out] | peak_val_p | Returns interpolated peak value if non-NULL

Returns
  Peak position with sub-sample accuracy

References osmo_cxvec::data, osmo_cxvec::len, osmo_cxvec_interpolate_point(), osmo_normsqf(), PEAK_EARLY_LATE, PEAK_WEIGH_WIN, and PEAK_WEIGH_WIN_CENTER.

## ◆ osmo_cxvec_peaks_scan()

int osmo_cxvec_peaks_scan | ( | const struct osmo_cxvec * | cv,
|  | int * | peaks_idx,
|  | int | N
| ) |  |

Find the index of the N highest energy ( ) peaks.

Parameters

  [in] | cv | Input complex vector
  [out] | peaks_idx | Return array of the peak indexes
  [in] | Size | of the peaks_idx return array

Returns
  Number of peaks (will be N if there is enough points)

References osmo_cxvec::data, osmo_cxvec::len, and osmo_normsqf().

## ◆ osmo_cxvec_rotate()

struct osmo_cxvec * osmo_cxvec_rotate | ( | const struct osmo_cxvec * | in,
|  | float | rps,
|  | struct osmo_cxvec * | out
| ) |  |

Rotate a complex vector (frequency shift)

Parameters

  [in] | in | Input complex vector
  [in] | rps | Rotation to apply in radian per sample
  [out] | out | Output complex vector

Returns
  The output complex vector (or NULL if error)

The output vector parameter 'out' can be NULL to allocate a new vector, or can be equal to the 'in' input vector to perform the transform in-place. If it's different, it must be long enough to contain the result (i.e. in->len)

References osmo_cxvec::data, osmo_cxvec::flags, osmo_cxvec::len, osmo_cxvec::max_len, and osmo_cxvec_alloc().

## ◆ osmo_cxvec_scale()

struct osmo_cxvec * osmo_cxvec_scale | ( | const struct osmo_cxvec * | in,
|  | float complex | scale,
|  | struct osmo_cxvec * | out
| ) |  |

Scale a complex vector (multiply by a constant)

Parameters

  [in] | in | Input complex vector
  [in] | scale | Factor to apply to each sample
  [out] | out | Output complex vector

Returns
  The output complex vector (or NULL if error)

The output vector parameter 'out' can be NULL to allocate a new vector, or can be equal to the 'in' input vector to perform the transform in-place. If it's different, it must be long enough to contain the result (i.e. in->len)

References osmo_cxvec::data, osmo_cxvec::flags, osmo_cxvec::len, osmo_cxvec::max_len, and osmo_cxvec_alloc().

## ◆ osmo_cxvec_sig_normalize()

struct osmo_cxvec * osmo_cxvec_sig_normalize | ( | const struct osmo_cxvec * | sig,
|  | int | decim,
|  | float | freq_shift,
|  | struct osmo_cxvec * | out
| ) |  |

'Normalize' an IQ signal and apply decimation/frequency shift

Parameters

  [in] | sig | Input complex signal
  [in] | decim | Decimation factor
  [in] | freq_shift | Frequency shift in radian per output sample
  [out] | out | Output complex vector

Returns
  The output complex vector (or NULL if error)

The operation performed are DC removal, amplitude normalization (divided by the standard deviation), decimation, frequency shift.

The output vector parameter 'out' can be NULL to allocate a new vector, or can be equal to the 'in' input vector to perform the transform in-place. If it's different, it must be long enough to contain the result (i.e. (sig->len + decim - 1) / decim)

References osmo_cxvec::data, osmo_cxvec::flags, osmo_cxvec::len, osmo_cxvec::max_len, osmo_cxvec_alloc(), and osmo_normsqf().

## ◆ osmo_normsqf()

static float osmo_normsqf | ( | float complex | c | ) |
| inlinestatic

Squared norm of a given complex.

Parameters

  [in] | c | Complex number for which to compute the squared norm

Returns

Referenced by _osmo_iqbal_estimate(), osmo_cxvec_peak_energy_find(), osmo_cxvec_peaks_scan(), and osmo_cxvec_sig_normalize().

## ◆ osmo_sinc()

static float osmo_sinc | ( | float | x | ) |
| inlinestatic

Unnormalized sinc function.

Parameters

  [in] | x | Value for which to compute the sinc function.

Returns
  The sinc(x) value

The function is defined as

Referenced by osmo_cxvec_delay(), and osmo_cxvec_interpolate_point().