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 :

$(f * g)[n] = \sum_{m=-\infty}^{\infty} f[m] \; g[n-m]$

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 :

$(f \star g)[n] = \sum_{m=-\infty}^{\infty} f^*[m] \; g[n+m]$

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)

$out(k) = in(k) \cdot e^{j \cdot rps \cdot k}$

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)

$out(k) = in(k) \cdot scale$

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 $\frac{\sin(x)}{x}$

Referenced by osmo_cxvec_delay(), and osmo_cxvec_interpolate_point().

Files

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ osmo_cxvec_conv_type

◆ osmo_cxvec_peak_alg

Function Documentation

◆ osmo_cxvec_convolve()

◆ osmo_cxvec_correlate()

◆ osmo_cxvec_delay()

◆ osmo_cxvec_interpolate_point()

◆ osmo_cxvec_peak_energy_find()

◆ osmo_cxvec_peaks_scan()

◆ osmo_cxvec_rotate()

◆ osmo_cxvec_scale()

◆ osmo_cxvec_sig_normalize()

◆ osmo_normsqf()

◆ osmo_sinc()