Files
file	iqbal.h
	Osmocom IQ balance utils header.

file	iqbal.c
	IQ balance utils implementation.

Data Structures
struct	osmo_iqbal_opts
	Processing options for the IQ balance optimization algorithm. More...

struct	_iqbal_estimate_state
	Cache for _osmo_iqbal_estimate when doing lots of calls. More...

struct	_iqbal_state
	Internal state structure for the IQ balance optimization algorithm. More...

Functions
void	osmo_iqbal_fix (float complex out, float complex in, unsigned int len, float mag, float phase)
	Apply IQ balance correction to a given complex buffer. More...

struct osmo_cxvec *	osmo_iqbal_cxvec_fix (const struct osmo_cxvec in, float mag, float phase, struct osmo_cxvec out)
	Apply IQ balance correction to a given complex vector. More...

float	osmo_iqbal_estimate (const float complex *data, int fft_size, int fft_count)
	Objectively estimate IQ balance in a given complex buffer. More...

float	osmo_iqbal_cxvec_estimate (const struct osmo_cxvec *sig, int fft_size, int fft_count)
	Objectively estimate IQ balance in a given complex vector. More...

int	osmo_iqbal_cxvec_optimize (const struct osmo_cxvec sig, float mag, float phase, const struct osmo_iqbal_opts opts)
	Finds the best IQ balance correction parameters for a given signal. More...

static void	_osmo_iqbal_estimate_release (struct _iqbal_estimate_state *state)
	Release a cache object created by _osmo_iqbal_estimate.

static float	_osmo_iqbal_estimate (const float complex data, int fft_size, int fft_count, struct _iqbal_estimate_state *state_p)
	Objectively estimate IQ balance in a given complex buffer. More...

static float	_iqbal_objfn_value (struct _iqbal_state *state, float x[2])
	Optimization objective function - Value. More...

static void	_iqbal_objfn_gradient (struct _iqbal_state *state, float x[2], float v, float grad[2])
	Optimization objective function - Gradient estimation. More...

static float	_iqbal_objfn_val_gradient (struct _iqbal_state *state, float x[2], float grad[2])
	Optimization objective function - Value & Gradient estimation. More...

Variables
const struct osmo_iqbal_opts	osmo_iqbal_default_opts
	Default values for the optimization algorithm.

const struct osmo_iqbal_opts	osmo_iqbal_default_opts
	Default values for the optimization algorithm. More...

Detailed Description

Function Documentation

◆ _iqbal_objfn_gradient()

static void _iqbal_objfn_gradient	(	struct _iqbal_state *	state,
		float	x[2],
		float	v,
		float	grad[2]
	)

static

Optimization objective function - Gradient estimation.

Parameters

[in]	state	Current state object of optimization loop
[in]	x	An array of 2 float for (mag,phase) point to evaluate at
[in]	v	The value of the objective function at point 'x'
[out]	grad	An array of 2 float for the estimated gradient at point 'x'

References _iqbal_objfn_value().

Referenced by _iqbal_objfn_val_gradient(), and osmo_iqbal_cxvec_optimize().

◆ _iqbal_objfn_val_gradient()

static float _iqbal_objfn_val_gradient	(	struct _iqbal_state *	state,
		float	x[2],
		float	grad[2]
	)

inlinestatic

Optimization objective function - Value & Gradient estimation.

Parameters

[in]	state	Current state object of optimization loop
[in]	x	An array of 2 float for (mag,phase) point to evaluate at
[out]	grad	An array of 2 float for the estimated gradient at point 'x'

Returns: The value of the objective function at point 'x'

References _iqbal_objfn_gradient(), and _iqbal_objfn_value().

Referenced by osmo_iqbal_cxvec_optimize().

◆ _iqbal_objfn_value()

static float _iqbal_objfn_value	(	struct _iqbal_state *	state,
		float	x[2]
	)

inlinestatic

Optimization objective function - Value.

Parameters

[in]	state	Current state object of optimization loop
[in]	x	An array of 2 float for (mag,phase) point to evaluate at

Returns: The value of the objective function at point 'x'

References _osmo_iqbal_estimate(), _iqbal_state::cache, osmo_cxvec::data, _iqbal_state::feval, osmo_iqbal_opts::fft_count, osmo_iqbal_opts::fft_size, _iqbal_state::opts, _iqbal_state::org, osmo_iqbal_cxvec_fix(), and _iqbal_state::tmp.

Referenced by _iqbal_objfn_gradient(), _iqbal_objfn_val_gradient(), and osmo_iqbal_cxvec_optimize().

◆ _osmo_iqbal_estimate()

static float _osmo_iqbal_estimate	(	const float complex *	data,
		int	fft_size,
		int	fft_count,
		struct _iqbal_estimate_state **	state_p
	)

static

Objectively estimate IQ balance in a given complex buffer.

Parameters

[in]	data	Input complex buffer (at least fft_size * fft_count samples)
[in]	fft_size	Size of the FFT to use internally
[in]	fft_count	The number of consecutive FFT to use internally
[out]	state_p	Cache object for multiple calls (can be NULL)

Returns: A number >= 0.0f estimating the IQ balance (the lower, the better)

The Cache object should only be used for multiple calls with the same parameters and the same size of input vector. Once you don't plan on using it anymore, you should call _osmo_iqbal_estimate_release . The initial pointer value should also be initialized to NULL.

References osmo_normsqf().

Referenced by _iqbal_objfn_value(), and osmo_iqbal_estimate().

◆ osmo_iqbal_cxvec_estimate()

float osmo_iqbal_cxvec_estimate	(	const struct osmo_cxvec *	sig,
		int	fft_size,
		int	fft_count
	)

Objectively estimate IQ balance in a given complex vector.

Parameters

[in]	sig	Input complex vector (at least fft_size * fft_count samples)
[in]	fft_size	Size of the FFT to use internally
[in]	fft_count	The number of consecutive FFT to use internally

Returns: A number >= 0.0f estimating the IQ balance (the lower, the better)

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

◆ osmo_iqbal_cxvec_fix()

struct osmo_cxvec * osmo_iqbal_cxvec_fix	(	const struct osmo_cxvec *	in,
		float	mag,
		float	phase,
		struct osmo_cxvec *	out
	)

Apply IQ balance correction to a given complex vector.

Parameters

[in]	in	Complex input vector
[in]	mag	Magnitude correction (approximated)
[in]	phase	Phase correction (approximated)
[out]	out	Complex output vector (can be NULL or equal to 'in')

Returns: The output complex vector (or NULL if error)

If the 'out' parameter is NULL, a new vector will be allocated See osmo_iqbal_fix for details of the correction applied.

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

Referenced by _iqbal_objfn_value().

◆ osmo_iqbal_cxvec_optimize()

int osmo_iqbal_cxvec_optimize	(	const struct osmo_cxvec *	sig,
		float *	mag,
		float *	phase,
		const struct osmo_iqbal_opts *	opts
	)

Finds the best IQ balance correction parameters for a given signal.

Parameters

[in]	sig	The input signal to optimize for
[in,out]	mag	Magnitude correction (See osmo_iqbal_fix)
[in,out]	phase	Phase correction (See osmo_iqbal_fix)
[in]	opts	Options of the optimization process (See osmo_iqbal_opts)

The mag and phase parameters are pointers to float. If in the options, the 'start_at_prev' is enabled, the initial values of those will be used and so they should be initialized appropriately.

References _iqbal_objfn_gradient(), _iqbal_objfn_val_gradient(), _iqbal_objfn_value(), _osmo_iqbal_estimate_release(), _iqbal_state::cache, _iqbal_state::feval, osmo_iqbal_opts::fft_count, osmo_iqbal_opts::fft_size, osmo_cxvec::len, osmo_iqbal_opts::max_iter, _iqbal_state::opts, _iqbal_state::org, osmo_cxvec_alloc(), osmo_cxvec_free(), osmo_iqbal_default_opts, osmo_iqbal_opts::start_at_prev, and _iqbal_state::tmp.

◆ osmo_iqbal_estimate()

float osmo_iqbal_estimate	(	const float complex *	data,
		int	fft_size,
		int	fft_count
	)

Objectively estimate IQ balance in a given complex buffer.

Parameters

[in]	data	Input complex buffer (at least fft_size * fft_count samples)
[in]	fft_size	Size of the FFT to use internally
[in]	fft_count	The number of consecutive FFT to use internally

Returns: A number >= 0.0f estimating the IQ balance (the lower, the better)

References _osmo_iqbal_estimate().

Referenced by osmo_iqbal_cxvec_estimate().

◆ osmo_iqbal_fix()

void osmo_iqbal_fix	(	float complex *	out,
		float complex *	in,
		unsigned int	len,
		float	mag,
		float	phase
	)

Apply IQ balance correction to a given complex buffer.

Parameters

[out]	out	Complex output buffer
[in]	in	Complex input buffer
[in]	len	Number of complex samples to process
[in]	mag	Magnitude correction (approximated)
[in]	phase	Phase correction (approximated)

The input and output buffers can be the same for in-place modification.

The applied transform is out[i] = (a * (1 + mag)) + (b + phase * a) * i (with in[i] = a+bi).

Referenced by osmo_iqbal_cxvec_fix().

Variable Documentation

◆ osmo_iqbal_default_opts

const struct osmo_iqbal_opts osmo_iqbal_default_opts

Initial value:

= {
        .fft_size       = 1024,
        .fft_count      = 8,
        .max_iter       = 25,
        .start_at_prev  = 1,
}

Default values for the optimization algorithm.

Referenced by osmo_iqbal_cxvec_optimize().

Files

Data Structures

Functions

Variables

Detailed Description

Function Documentation

◆ _iqbal_objfn_gradient()

◆ _iqbal_objfn_val_gradient()

◆ _iqbal_objfn_value()

◆ _osmo_iqbal_estimate()

◆ osmo_iqbal_cxvec_estimate()

◆ osmo_iqbal_cxvec_fix()

◆ osmo_iqbal_cxvec_optimize()

◆ osmo_iqbal_estimate()

◆ osmo_iqbal_fix()

Variable Documentation

◆ osmo_iqbal_default_opts