libosmodsp: IQ balance utilities

libosmodsp 0.4.0.12-f6f4 Osmocom DSP library

Files | Data Structures | Functions | Variables
IQ balance utilities

## 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().