C++ API Reference

API reference for the Genalyzer C++ implementation library (genalyzer_impl namespace). These are the core C++ functions that the C and Python bindings wrap.

Enumerations

namespace genalyzer_impl

Public enumerations for the genalyzer library.

Enums

enum class AnalysisType : int

Type of analysis performed.

Values:

enumerator DNL

Differential nonlinearity analysis.

enumerator Fourier

Fourier (spectral) analysis.

enumerator Histogram

Histogram (code density) analysis.

enumerator INL

Integral nonlinearity analysis.

enumerator Waveform

Time-domain waveform analysis.

enum class CodeFormat : int

ADC code format.

Values:

enumerator OffsetBinary

Unsigned offset binary encoding.

enumerator TwosComplement

Signed two’s complement encoding.

enum class DnlSignal : int

Signal type used for DNL computation.

Values:

enumerator Ramp

Linear ramp stimulus.

enumerator Tone

Sinusoidal (tone) stimulus.

enum class FACompTag : int

Fourier analysis component classification tag.

Determines how a spectral component is categorized when computing aggregate metrics. Components not tagged as DC, Signal, or a distortion type are treated as noise.

Values:

enumerator DC

DC component (always Bin 0).

enumerator Signal

Signal component.

enumerator HD

Harmonic distortion.

enumerator IMD

Intermodulation distortion.

enumerator ILOS

Interleaving offset component.

enumerator ILGT

Interleaving gain/timing/BW component.

enumerator CLK

Clock sub-harmonic component.

enumerator UserDist

User-designated distortion component.

enumerator Noise

Noise component (e.g., WorstOther).

enum class FASsb : int

Fourier analysis single-side-bin group selector.

Controls the number of FFT bins assigned to each side of a tone’s center bin for different component groups.

Values:

enumerator Default

Default SSB (applies to auto-generated components).

enumerator DC

SSB for the DC component.

enumerator Signal

SSB for signal components.

enumerator WO

SSB for worst-other components.

enum class FreqAxisFormat : int

Output format for frequency axis values.

Values:

enumerator Bins

Frequency expressed as FFT bin indices.

enumerator Freq

Frequency expressed in Hz.

enumerator Norm

Normalized frequency (relative to sample rate).

enum class FreqAxisType : int

Frequency axis layout type.

Values:

enumerator DcCenter

DC at center: [-fs/2, fs/2).

enumerator DcLeft

DC at left: [0, fs).

enumerator Real

Real (one-sided): [0, fs/2].

enum class InlLineFit : int

Line-fit method for INL computation.

Values:

enumerator BestFit

Remove a least-squares best-fit line.

enumerator EndFit

Remove an endpoint-fit line.

enumerator NoFit

Do not remove any line (raw cumulative sum).

enum class RfftScale : int

dBFS scaling convention for real FFT output.

Controls how full-scale is defined for dBFS measurements.

Values:

enumerator DbfsDc

Full-scale sinusoid measures -3 dBFS.

enumerator DbfsSin

Full-scale sinusoid measures 0 dBFS.

enumerator Native

Full-scale sinusoid measures -6 dBFS.

enum class Window : int

Window function for FFT computation.

Values:

enumerator BlackmanHarris

Blackman-Harris window.

enumerator Hann

Hann window.

enumerator NoWindow

No window (rectangular).

enum class FACompType : int

Values:

enumerator DC
enumerator FixedTone
enumerator MaxTone
enumerator WOTone
enum class FAResult : int

Values:

enumerator AnalysisType
enumerator SignalType
enumerator NFFT
enumerator DataSize
enumerator FBin
enumerator FData
enumerator FSample
enumerator FShift
enumerator FSNR
enumerator SNR
enumerator SINAD
enumerator SFDR
enumerator ABN
enumerator NSD
enumerator CarrierIndex
enumerator MaxSpurIndex
enumerator AB_Width
enumerator AB_I1
enumerator AB_I2
enumerator AB_NBins
enumerator AB_RSS
enumerator Signal_NBins
enumerator Signal_RSS
enumerator CLK_NBins
enumerator CLK_RSS
enumerator HD_NBins
enumerator HD_RSS
enumerator ILOS_NBins
enumerator ILOS_RSS
enumerator ILGT_NBins
enumerator ILGT_RSS
enumerator IMD_NBins
enumerator IMD_RSS
enumerator UserDist_NBins
enumerator UserDist_RSS
enumerator THD_NBins
enumerator THD_RSS
enumerator ILV_NBins
enumerator ILV_RSS
enumerator Dist_NBins
enumerator Dist_RSS
enumerator Noise_NBins
enumerator Noise_RSS
enumerator NAD_NBins
enumerator NAD_RSS
enumerator __SIZE__
enum class FAToneResult : int

Values:

enumerator OrderIndex
enumerator Tag
enumerator Freq
enumerator FFinal
enumerator FWAvg
enumerator I1
enumerator I2
enumerator NBins
enumerator InBand
enumerator Mag
enumerator Mag_dBFS
enumerator Mag_dBc
enumerator Phase
enumerator Phase_c
enumerator __SIZE__
enum class FPFormat

Values:

enumerator Auto
enumerator Eng
enumerator Fix
enumerator Sci
enum class ObjectType

Values:

enumerator FourierAnalysis

Array Operations

namespace genalyzer_impl

Public enumerations for the genalyzer library.

Functions

void abs(const real_t *in_data, size_t in_size, real_t *out_data, size_t out_size)

Compute the absolute value (magnitude) of each complex number.

Input is an interleaved real/imaginary array of size 2N. Output is a real array of size N containing the magnitude of each complex element.

Parameters:

  • in_data – Pointer to interleaved complex input data (re, im, re, im, …).

  • in_size – Number of elements in in_data (must be even).

  • out_data – Pointer to output array for magnitudes.

  • out_size – Number of elements in out_data (must be in_size / 2).

void angle(const real_t *in_data, size_t in_size, real_t *out_data, size_t out_size)

Compute the phase angle (argument) of each complex number.

Input is an interleaved real/imaginary array of size 2N. Output is a real array of size N containing the phase angle in radians of each complex element.

Parameters:

  • in_data – Pointer to interleaved complex input data.

  • in_size – Number of elements in in_data (must be even).

  • out_data – Pointer to output array for phase angles (radians).

  • out_size – Number of elements in out_data (must be in_size / 2).

void db(const real_t *in_data, size_t in_size, real_t *out_data, size_t out_size)

Convert each complex number to decibels.

Computes 10*log10(re^2 + im^2) for each complex element with a lower bound to avoid -infinity. Input is interleaved real/imaginary, output is real.

Parameters:

  • in_data – Pointer to interleaved complex input data.

  • in_size – Number of elements in in_data (must be even).

  • out_data – Pointer to output array for dB values.

  • out_size – Number of elements in out_data (must be in_size / 2).

void db10(const real_t *in_data, size_t in_size, real_t *out_data, size_t out_size)

Convert each real value to decibels using 10*log10(x).

A lower bound is applied to avoid -infinity for zero or negative values. Input and output are real arrays of the same size.

Parameters:

  • in_data – Pointer to input real data.

  • in_size – Number of elements in in_data.

  • out_data – Pointer to output array for dB values.

  • out_size – Number of elements in out_data (must equal in_size).

void db20(const real_t *in_data, size_t in_size, real_t *out_data, size_t out_size)

Convert each real value to decibels using 20*log10(x).

A lower bound is applied to avoid -infinity for zero or negative values. Input and output are real arrays of the same size.

Parameters:

  • in_data – Pointer to input real data.

  • in_size – Number of elements in in_data.

  • out_data – Pointer to output array for dB values.

  • out_size – Number of elements in out_data (must equal in_size).

void norm(const real_t *in_data, size_t in_size, real_t *out_data, size_t out_size)

Compute the squared magnitude (norm) of each complex number.

Computes re^2 + im^2 for each complex element. Input is interleaved real/imaginary of size 2N, output is real of size N.

Parameters:

  • in_data – Pointer to interleaved complex input data.

  • in_size – Number of elements in in_data (must be even).

  • out_data – Pointer to output array for squared magnitudes.

  • out_size – Number of elements in out_data (must be in_size / 2).

Code Density

namespace genalyzer_impl

Public enumerations for the genalyzer library.

Functions

size_t code_density_size(int n, CodeFormat format)

Return the number of histogram bins for a given ADC resolution and code format.

Parameters:

  • n – ADC resolution in bits.

  • format – Code format (e.g., TwosComplement, OffsetBinary).

Returns:

Number of codes (2^n).

size_t code_densityx_size(int64_t min, int64_t max)

Return the number of histogram bins for an explicit code range.

Parameters:

  • min – Minimum code value (inclusive).

  • max – Maximum code value (inclusive).

Returns:

Number of codes (max - min + 1).

void code_axis(real_t *data, size_t size, int n, CodeFormat format)

Generate a code axis array for an ADC with the given resolution.

Values span the full code range determined by the code format (e.g., -2^(n-1) to 2^(n-1)-1 for two’s complement).

Parameters:

  • data – Pointer to output array for code axis values.

  • size – Number of elements in data (use code_density_size()).

  • n – ADC resolution in bits.

  • format – Code format.

void code_axisx(real_t *data, size_t size, int64_t min, int64_t max)

Generate a code axis array for an explicit code range [min, max].

Output values are integers from min to max inclusive.

Parameters:

  • data – Pointer to output array for code axis values.

  • size – Number of elements in data (use code_densityx_size()).

  • min – Minimum code value (inclusive).

  • max – Maximum code value (inclusive).

void dnl(real_t *dnl_data, size_t dnl_size, const uint64_t *hist_data, size_t hist_size, DnlSignal type)

Compute Differential Nonlinearity (DNL) from a histogram.

DNL measures the deviation of each code bin width from the ideal 1-LSB step size. The computation method depends on the signal type (ramp or sinusoidal tone).

Parameters:

  • dnl_data – Pointer to output DNL array.

  • dnl_size – Number of elements in dnl_data.

  • hist_data – Pointer to input histogram data.

  • hist_size – Number of elements in hist_data.

  • type – Signal type used to acquire the histogram (Ramp or Tone).

std::map<str_t, real_t> dnl_analysis(const real_t *data, size_t size)

Compute summary statistics from DNL data.

Results include min, max, average, RMS, and indices of extrema and non-missing codes.

Parameters:

  • data – Pointer to DNL data array.

  • size – Number of elements in data.

Returns:

Map of metric names to values.

const std::vector<str_t> &dnl_analysis_ordered_keys()

Return the ordered list of result keys for dnl_analysis().

Returns:

Reference to a vector of key strings in canonical order.

template<typename T>
void hist(uint64_t *hist_data, size_t hist_size, const T *wf_data, size_t wf_size, int n, CodeFormat format, bool preserve)

Compute a histogram (code density) of a quantized waveform.

Counts the number of occurrences of each code for the given ADC resolution and code format.

Template Parameters:

T – Integer sample type.

Parameters:

  • hist_data – Pointer to histogram output array.

  • hist_size – Number of elements in hist_data (use code_density_size()).

  • wf_data – Pointer to input waveform samples.

  • wf_size – Number of elements in wf_data.

  • n – ADC resolution in bits.

  • format – Code format.

  • preserve – If true, add counts to existing histogram data; if false, initialize the histogram to zero first.

template<typename T>
void histx(uint64_t *hist_data, size_t hist_size, const T *wf_data, size_t wf_size, int64_t min, int64_t max, bool preserve)

Compute a histogram of a quantized waveform using explicit code bounds.

Uses explicit min/max code values instead of resolution and code format.

Template Parameters:

T – Integer sample type.

Parameters:

  • hist_data – Pointer to histogram output array.

  • hist_size – Number of elements in hist_data (use code_densityx_size()).

  • wf_data – Pointer to input waveform samples.

  • wf_size – Number of elements in wf_data.

  • min – Minimum code value (inclusive).

  • max – Maximum code value (inclusive).

  • preserve – If true, add counts to existing histogram data; if false, initialize the histogram to zero first.

std::map<str_t, real_t> hist_analysis(const uint64_t *data, size_t size)

Compute summary statistics from histogram data.

Results include sum, first/last non-zero bin indices, and non-zero range.

Parameters:

  • data – Pointer to histogram data array.

  • size – Number of elements in data.

Returns:

Map of metric names to values.

const std::vector<str_t> &hist_analysis_ordered_keys()

Return the ordered list of result keys for hist_analysis().

Returns:

Reference to a vector of key strings in canonical order.

void inl(real_t *inl_data, size_t inl_size, const real_t *dnl_data, size_t dnl_size, InlLineFit fit)

Compute Integral Nonlinearity (INL) by cumulative summation of DNL.

INL measures the deviation of the transfer function from an ideal straight line. The line-fit parameter controls whether/how a best-fit or endpoint line is removed from the result.

Parameters:

  • inl_data – Pointer to output INL array.

  • inl_size – Number of elements in inl_data.

  • dnl_data – Pointer to input DNL data.

  • dnl_size – Number of elements in dnl_data.

  • fit – Line-fit method (BestFit, EndFit, or NoFit).

std::map<str_t, real_t> inl_analysis(const real_t *data, size_t size)

Compute summary statistics from INL data.

Results include min, max, and their indices.

Parameters:

  • data – Pointer to INL data array.

  • size – Number of elements in data.

Returns:

Map of metric names to values.

const std::vector<str_t> &inl_analysis_ordered_keys()

Return the ordered list of result keys for inl_analysis().

Returns:

Reference to a vector of key strings in canonical order.

Fourier Analysis

class fourier_analysis : public genalyzer_impl::object

Central class for Fourier-analysis-based RF performance metrics.

Computes SNR, SINAD, SFDR, THD, and other spectral metrics for data-converter outputs. Users configure the analysis by defining signal components, setting sample/data rates, and specifying distortion orders before calling analyze().

Public Functions

fourier_analysis_results analyze(const real_t *in_data, const size_t in_size, const size_t nfft, FreqAxisType axis_type) const

Run Fourier analysis on FFT magnitude-squared data.

Identifies configured signal, distortion, and noise components in the spectrum and computes performance metrics (SNR, SINAD, SFDR, THD, etc.).

Parameters:

  • in_data – Pointer to magnitude-squared FFT data.

  • in_size – Number of elements in in_data.

  • nfft – FFT size used to produce in_data.

  • axis_type – Frequency axis type of the input data.

Returns:

A fourier_analysis_results object containing all computed metrics.

void add_fixed_tone(const str_t &key, FACompTag tag, const str_t &freq, int ssb)

Add a tone component at a fixed frequency.

The frequency is specified as an expression string that may reference user-defined variables.

Parameters:

  • key – Unique key identifying this component.

  • tag – Classification tag (Signal, HD, IMD, UserDist, etc.).

  • freq – Frequency expression string.

  • ssb – Number of single-side bins (-1 to use the default).

void add_max_tone(const str_t &key, FACompTag tag, const str_t &center, const str_t &width, int ssb)

Add a tone component located at the spectral maximum within a search range.

The search range is defined by center and width expression strings.

Parameters:

  • key – Unique key identifying this component.

  • tag – Classification tag (Signal, HD, IMD, UserDist, etc.).

  • center – Center frequency expression for the search range.

  • width – Width expression for the search range.

  • ssb – Number of single-side bins (-1 to use the default).

void remove_comp(const str_t &key)

Remove a previously added user-defined component.

Parameters:

key – Key of the component to remove.

inline str_t ab_center() const

Get the analysis band center expression.

inline str_t ab_width() const

Get the analysis band width expression.

inline std::set<int> clk() const

Get the set of clock sub-harmonic divisors.

inline str_t fdata() const

Get the data rate expression.

inline str_t fsample() const

Get the sample rate expression.

inline str_t fshift() const

Get the shift frequency expression.

inline int hd() const

Get the maximum harmonic distortion order.

inline std::set<int> ilv() const

Get the set of interleaving factors.

inline int imd() const

Get the maximum intermodulation distortion order.

inline int wo() const

Get the number of worst-other tones.

int ssb(FASsb group) const

Get the number of single-side bins for a component group.

Parameters:

group – Component group (DC, Signal, WO, or Default).

Returns:

Number of single-side bins for the specified group.

void set_analysis_band(const str_t &center, const str_t &width)

Set the analysis band center and width.

Only spectral content within the analysis band is included in metric computations.

Parameters:

  • center – Center frequency expression string.

  • width – Width expression string.

void set_clk(const std::set<int> &clk)

Set clock sub-harmonic divisors.

Clock spurs at fs/N are identified and classified as CLK components.

Parameters:

clk – Set of integer divisors.

void set_fdata(const str_t &expr)

Set the data rate as an expression string.

Parameters:

expr – Data rate expression (may reference user-defined variables).

void set_fsample(const str_t &expr)

Set the sample rate as an expression string.

Parameters:

expr – Sample rate expression (may reference user-defined variables).

void set_fshift(const str_t &expr)

Set the shift frequency as an expression string.

The shift frequency represents the cumulative frequency translation applied after sampling.

Parameters:

expr – Shift frequency expression.

void set_hd(int n)

Set the maximum harmonic distortion order.

Harmonics 2 through n of each signal tone are automatically generated.

Parameters:

n – Maximum harmonic order.

void set_ilv(const std::set<int> &ilv)

Set interleaving factors.

Interleaving spurs at fs/N offsets are identified and classified.

Parameters:

ilv – Set of interleaving factors.

void set_imd(int n)

Set the maximum intermodulation distortion order.

IMD products up to order n are automatically generated when multiple signal tones are present.

Parameters:

n – Maximum IMD order.

void set_ssb(FASsb group, int ssb)

Set the number of single-side bins for a component group.

Each tone occupies 2*ssb+1 bins total (ssb bins on each side of the center bin).

Parameters:

  • group – Component group (DC, Signal, WO, or Default).

  • ssb – Number of single-side bins.

void set_var(const str_t &key, real_t x)

Set the value of an expression variable.

Variables can be referenced in frequency expressions (e.g., fdata, fshift, tone frequencies).

Parameters:

  • key – Variable name.

  • x – Variable value.

void set_wo(int n)

Set the number of worst-other tones to identify.

Worst-others are the n largest spectral components not accounted for by other defined components.

Parameters:

n – Number of worst-other tones.

inline bool is_available(const str_t &key) const

Check whether a key is valid, not reserved, and not already in use.

Parameters:

key – Key to check.

Returns:

True if the key is available for use.

inline bool is_comp(const str_t &key) const

Check whether a key is used by a user-defined component.

Parameters:

key – Key to check.

Returns:

True if the key is in use by a component.

inline bool is_var(const str_t &key) const

Check whether a key is used by a user-defined variable.

Parameters:

key – Key to check.

Returns:

True if the key is in use by a variable.

str_t preview(bool cplx) const

Return a string preview of the analysis configuration.

Shows all configured components and their frequencies.

Parameters:

cplx – If true, include complex-specific components (e.g., images).

Returns:

Configuration preview as a formatted string.

void reset()

Reset all configuration to default values.

Removes all user-defined components and variables.

size_t results_size(size_t in_size, size_t nfft) const

Return the number of key-value pairs in the analysis results.

Parameters:

  • in_size – Number of elements in the input data array.

  • nfft – FFT size.

Returns:

Number of result key-value pairs.

Public Members

bool clk_as_noise

If true, classify clock components as noise rather than distortion.

bool dc_as_dist

If true, classify DC as distortion rather than noise.

bool en_conv_offset

If true, enable the converter offset component.

bool en_fund_images

If true, enable fundamental image components (for complex FFT analysis).

bool en_quad_errors

If true, enable quadrature error tone components (image, gain/phase imbalance).

bool ilv_as_noise

If true, classify interleaving components as noise rather than distortion.

Public Static Functions

static inline std::shared_ptr<fourier_analysis> create()

Factory method to create a new fourier_analysis object.

Returns:

Shared pointer to a new fourier_analysis instance.

static std::shared_ptr<fourier_analysis> load(const str_t &filename)

Load a fourier_analysis configuration from a JSON file.

Parameters:

filename – Path to the JSON configuration file.

Returns:

Shared pointer to the loaded fourier_analysis instance.

static bool is_reserved(const str_t &key)

Check whether a component key is reserved (used internally).

Parameters:

key – Key to check.

Returns:

True if the key is reserved.

static bool is_valid(const str_t &key)

Check whether a string is a valid component key format.

Parameters:

key – Key to validate.

Returns:

True if the key has a valid format.

Fourier Transforms

namespace genalyzer_impl

Public enumerations for the genalyzer library.

Functions

void fft(const real_t *i_data, size_t i_size, const real_t *q_data, size_t q_size, real_t *out_data, size_t out_size, size_t navg, size_t nfft, Window window)

Compute the complex FFT of normalized (floating-point) I/Q data.

Supports averaging over multiple records. If q_size is 0, i_data contains interleaved I/Q samples; otherwise i_data and q_data are separate I and Q channels. Output is an interleaved real/imaginary complex FFT result.

Parameters:

  • i_data – Pointer to I data (or interleaved I/Q if q_size is 0).

  • i_size – Number of elements in i_data.

  • q_data – Pointer to Q data (may be nullptr if q_size is 0).

  • q_size – Number of elements in q_data (0 for interleaved input).

  • out_data – Pointer to output array for interleaved complex FFT result.

  • out_size – Number of elements in out_data (use fft_size() to compute).

  • navg – Number of records to average (0 for auto-detect).

  • nfft – FFT size (0 for auto-detect).

  • window – Window function to apply before the FFT.

template<typename T>
void fft(const T *i_data, size_t i_size, const T *q_data, size_t q_size, real_t *out_data, size_t out_size, int n, size_t navg, size_t nfft, Window window, CodeFormat format)

Compute the complex FFT of quantized (integer) I/Q data.

Template supports int16_t, int32_t, and int64_t. Data is internally normalized to floating-point before the FFT computation.

Template Parameters:

T – Integer sample type (int16_t, int32_t, or int64_t).

Parameters:

  • i_data – Pointer to I data (or interleaved I/Q if q_size is 0).

  • i_size – Number of elements in i_data.

  • q_data – Pointer to Q data (may be nullptr if q_size is 0).

  • q_size – Number of elements in q_data (0 for interleaved input).

  • out_data – Pointer to output array for interleaved complex FFT result.

  • out_size – Number of elements in out_data (use fft_size() to compute).

  • n – ADC resolution in bits.

  • navg – Number of records to average (0 for auto-detect).

  • nfft – FFT size (0 for auto-detect).

  • window – Window function to apply before the FFT.

  • format – Code format of the input samples.

size_t fft_size(size_t i_size, size_t q_size, size_t &navg, size_t &nfft)

Compute the required output array size for fft().

Also resolves navg and nfft if they are set to 0 (auto-detect).

Parameters:

  • i_size – Number of elements in the I data array.

  • q_size – Number of elements in the Q data array (0 for interleaved).

  • navg – Number of averages (input/output; resolved if 0).

  • nfft – FFT size (input/output; resolved if 0).

Returns:

Required output array size (2 * nfft for interleaved complex output).

void rfft(const real_t *in_data, size_t in_size, real_t *out_data, size_t out_size, size_t navg, size_t nfft, Window window, RfftScale scale)

Compute the real FFT (one-sided spectrum) of normalized data.

Output is interleaved real/imaginary of size nfft+2 (i.e., nfft/2+1 complex bins). The scale parameter controls the dBFS convention.

Parameters:

  • in_data – Pointer to real input data.

  • in_size – Number of elements in in_data.

  • out_data – Pointer to output array for interleaved complex FFT result.

  • out_size – Number of elements in out_data (use rfft_size() to compute).

  • navg – Number of records to average (0 for auto-detect).

  • nfft – FFT size (0 for auto-detect).

  • window – Window function to apply before the FFT.

  • scale – dBFS scaling convention.

template<typename T>
void rfft(const T *in_data, size_t in_size, real_t *out_data, size_t out_size, int n, size_t navg, size_t nfft, Window window, CodeFormat format, RfftScale scale)

Compute the real FFT of quantized (integer) data.

Template supports int16_t, int32_t, and int64_t. Data is internally normalized before the FFT computation.

Template Parameters:

T – Integer sample type (int16_t, int32_t, or int64_t).

Parameters:

  • in_data – Pointer to quantized input data.

  • in_size – Number of elements in in_data.

  • out_data – Pointer to output array for interleaved complex FFT result.

  • out_size – Number of elements in out_data (use rfft_size() to compute).

  • n – ADC resolution in bits.

  • navg – Number of records to average (0 for auto-detect).

  • nfft – FFT size (0 for auto-detect).

  • window – Window function to apply before the FFT.

  • format – Code format of the input samples.

  • scale – dBFS scaling convention.

size_t rfft_size(size_t in_size, size_t &navg, size_t &nfft)

Compute the required output array size for rfft().

Also resolves navg and nfft if they are set to 0 (auto-detect).

Parameters:

  • in_size – Number of elements in the input data array.

  • navg – Number of averages (input/output; resolved if 0).

  • nfft – FFT size (input/output; resolved if 0).

Returns:

Required output array size (nfft + 2).

Fourier Utilities

namespace genalyzer_impl

Public enumerations for the genalyzer library.

Functions

real_t alias(real_t fs, real_t freq, FreqAxisType axis_type)

Compute the aliased frequency for a given sample rate.

Maps the input frequency into the appropriate Nyquist zone based on the axis type: DcCenter maps to [-fs/2, fs/2), DcLeft maps to [0, fs), and Real maps to [0, fs/2].

Parameters:

  • fs – Sample rate in Hz.

  • freq – Input frequency in Hz.

  • axis_type – Frequency axis type determining the alias range.

Returns:

The aliased frequency in Hz.

real_t coherent(size_t nfft, real_t fs, real_t freq)

Compute the nearest coherent frequency for a given FFT size.

Coherent sampling ensures the signal frequency lands exactly on an FFT bin, eliminating spectral leakage. For power-of-2 FFT sizes, the returned frequency corresponds to an odd number of cycles within the record.

Parameters:

  • nfft – FFT size.

  • fs – Sample rate in Hz.

  • freq – Desired frequency in Hz.

Returns:

The nearest coherent frequency in Hz.

void fftshift(const real_t *in_data, size_t in_size, real_t *out_data, size_t out_size)

Shift the zero-frequency component to the center of the array.

Performs a circular shift by N/2 (rounded up for odd sizes), converting a DC-left spectrum to a DC-center spectrum. Supports in-place operation (i.e., in_data and out_data may point to the same buffer).

Parameters:

  • in_data – Pointer to input array.

  • in_size – Number of elements in in_data.

  • out_data – Pointer to output array.

  • out_size – Number of elements in out_data (must equal in_size).

void freq_axis(real_t *data, size_t size, size_t nfft, FreqAxisType axis_type, real_t fs, FreqAxisFormat axis_format)

Generate a frequency axis array for plotting FFT results.

Supports DC-center [-fs/2, fs/2), DC-left [0, fs), and real [0, fs/2] layouts. Output values can be expressed in bins, Hz, or normalized frequency.

Parameters:

  • data – Pointer to output array for frequency axis values.

  • size – Number of elements in data (use freq_axis_size()).

  • nfft – FFT size.

  • axis_type – Frequency axis layout type.

  • fs – Sample rate in Hz.

  • axis_format – Output format (bins, Hz, or normalized).

void ifftshift(const real_t *in_data, size_t in_size, real_t *out_data, size_t out_size)

Inverse of fftshift: shift the zero-frequency component back to the left of the array.

Performs a circular shift of N/2 (rounded down), converting a DC-center spectrum to a DC-left spectrum. Supports in-place operation.

Parameters:

  • in_data – Pointer to input array.

  • in_size – Number of elements in in_data.

  • out_data – Pointer to output array.

  • out_size – Number of elements in out_data (must equal in_size).

size_t freq_axis_size(size_t nfft, FreqAxisType axis_type)

Return the number of elements in a frequency axis array.

For the Real axis type, returns nfft/2 + 1. For complex axis types (DcCenter, DcLeft), returns nfft.

Parameters:

  • nfft – FFT size.

  • axis_type – Frequency axis type.

Returns:

Number of elements in the frequency axis array.

Object Manager

namespace genalyzer_impl

Public enumerations for the genalyzer library.

namespace manager

Public API for the global object manager.

The manager stores named objects (e.g., fourier_analysis configurations) that can be retrieved, compared, serialized, and removed by key.

Functions

void clear()

Remove all objects from the global object manager.

bool contains(const str_t &key, bool throw_if_not_found = false)

Check whether an object with the given key exists in the manager.

Parameters:

  • key – Key to look up.

  • throw_if_not_found – If true, throw an exception when the key is not found.

Returns:

True if the key exists, false otherwise.

bool equal(const str_t &key1, const str_t &key2)

Compare two managed objects for equality.

Parameters:

  • key1 – Key of the first object.

  • key2 – Key of the second object.

Returns:

True if the objects are equal, false otherwise.

void remove(const str_t &key)

Remove the object with the given key from the manager.

Parameters:

key – Key of the object to remove.

str_t save(const str_t &key, const str_t &filename = "")

Serialize the object with the given key to a JSON file.

If filename is empty, a default filename is generated from the key.

Parameters:

  • key – Key of the object to save.

  • filename – Output file path (empty for auto-generated name).

Returns:

The filename that was written.

size_t size()

Return the number of objects currently stored in the manager.

Returns:

Object count.

str_t to_string(const str_t &key = "")

Return a string representation of a managed object.

If key is empty, returns a summary of all objects in the manager.

Parameters:

key – Key of the object (empty for summary of all objects).

Returns:

String representation.

str_t type_str(const str_t &key)

Return the type name of a managed object as a string.

Parameters:

key – Key of the object.

Returns:

Type name string.

void add_object(const str_t &key, object::pointer obj, bool replace)
str_t get_filename_from_object_key(const str_t &key, str_t filename)
object::pointer get_object(const str_t &key)
ObjectType type(const str_t &key)

Variables

static const str_t key_pattern = "[[:alpha:]][[:alnum:]._]*"

Signal Processing

namespace genalyzer_impl

Public enumerations for the genalyzer library.

Functions

template<typename T>
void downsample(const T *in_data, size_t in_size, T *out_data, size_t out_size, int ratio, bool interleaved)

Decimate a waveform by keeping every Nth sample.

If interleaved is true, the input is treated as interleaved I/Q pairs and decimation preserves pair alignment.

Template Parameters:

T – Sample type.

Parameters:

  • in_data – Pointer to input data.

  • in_size – Number of elements in in_data.

  • out_data – Pointer to output (decimated) data.

  • out_size – Number of elements in out_data (use downsample_size()).

  • ratio – Decimation ratio (keep every ratio-th sample).

  • interleaved – If true, treat data as interleaved I/Q pairs.

size_t downsample_size(size_t in_size, int ratio, bool interleaved)

Return the output array size for downsample().

Parameters:

  • in_size – Number of elements in the input array.

  • ratio – Decimation ratio.

  • interleaved – If true, input is interleaved I/Q pairs.

Returns:

Required output array size.

void fshift(const real_t *i_data, size_t i_size, const real_t *q_data, size_t q_size, real_t *out_data, size_t out_size, real_t fs, real_t _fshift)

Apply a frequency shift to normalized (floating-point) complex data.

Multiplies the input by exp(j*2*pi*fshift*n/fs). If q_size is 0, i_data contains interleaved I/Q; otherwise i_data and q_data are separate I and Q channels. Output is always interleaved I/Q.

Parameters:

  • i_data – Pointer to I data (or interleaved I/Q if q_size is 0).

  • i_size – Number of elements in i_data.

  • q_data – Pointer to Q data (may be nullptr if q_size is 0).

  • q_size – Number of elements in q_data (0 for interleaved input).

  • out_data – Pointer to output array for interleaved I/Q result.

  • out_size – Number of elements in out_data (use fshift_size()).

  • fs – Sample rate in Hz.

  • _fshift – Frequency shift in Hz.

template<typename T>
void fshift(const T *i_data, size_t i_size, const T *q_data, size_t q_size, T *out_data, size_t out_size, int n, real_t fs, real_t _fshift, CodeFormat format)

Apply a frequency shift to quantized (integer) complex data.

Results are rounded and clamped to the valid code range for the given resolution and format.

Template Parameters:

T – Integer sample type (int16_t, int32_t, or int64_t).

Parameters:

  • i_data – Pointer to I data (or interleaved I/Q if q_size is 0).

  • i_size – Number of elements in i_data.

  • q_data – Pointer to Q data (may be nullptr if q_size is 0).

  • q_size – Number of elements in q_data (0 for interleaved input).

  • out_data – Pointer to output array for interleaved I/Q result.

  • out_size – Number of elements in out_data (use fshift_size()).

  • n – ADC resolution in bits.

  • fs – Sample rate in Hz.

  • _fshift – Frequency shift in Hz.

  • format – Code format of the input and output samples.

size_t fshift_size(size_t i_size, size_t q_size)

Return the output array size for fshift().

Parameters:

  • i_size – Number of elements in the I data array.

  • q_size – Number of elements in the Q data array (0 for interleaved).

Returns:

Required output array size.

template<typename T>
void normalize(const T *in_data, size_t in_size, real_t *out_data, size_t out_size, int n, CodeFormat format)

Convert quantized integer samples to normalized floating-point values.

Output values are in the range [-1, 1). For offset binary, the offset is subtracted before scaling. For two’s complement, values are scaled directly by 2/2^n.

Template Parameters:

T – Integer sample type.

Parameters:

  • in_data – Pointer to input quantized data.

  • in_size – Number of elements in in_data.

  • out_data – Pointer to output normalized data.

  • out_size – Number of elements in out_data (must equal in_size).

  • n – ADC resolution in bits.

  • format – Code format of the input samples.

void polyval(const real_t *in_data, size_t in_size, real_t *out_data, size_t out_size, const real_t *c_data, size_t c_size)

Evaluate a polynomial at each point in the input array.

Uses Horner’s method. Coefficients are ordered as [c0, c1, c2, …] where y = c0 + c1*x + c2*x^2 + … This is useful for modeling nonlinear distortion.

Parameters:

  • in_data – Pointer to input data (x values).

  • in_size – Number of elements in in_data.

  • out_data – Pointer to output data (y values).

  • out_size – Number of elements in out_data (must equal in_size).

  • c_data – Pointer to polynomial coefficients [c0, c1, c2, …].

  • c_size – Number of coefficients.

template<typename T>
void quantize(const real_t *in_data, size_t in_size, T *out_data, size_t out_size, real_t fsr, int n, real_t noise, CodeFormat format)

Quantize floating-point samples to integer codes.

Quantizes with the given full-scale range and resolution. Optionally adds Gaussian quantization noise. Output codes are clamped to the valid range for the specified resolution and format.

Template Parameters:

T – Integer output type.

Parameters:

  • in_data – Pointer to input floating-point data.

  • in_size – Number of elements in in_data.

  • out_data – Pointer to output quantized data.

  • out_size – Number of elements in out_data (must equal in_size).

  • fsr – Full-scale range.

  • n – ADC resolution in bits.

  • noise – RMS level of additive Gaussian quantization noise (0 for none).

  • format – Code format for the output samples.

Waveforms

namespace genalyzer_impl

Public enumerations for the genalyzer library.

Functions

void cos(real_t *data, size_t size, real_t fs, real_t ampl, real_t freq, real_t phase, real_t td, real_t tj)

Generate a cosine waveform.

Computes data[i] = ampl * cos(2*pi*freq*(i/fs + td) + phase). If tj is greater than zero, Gaussian aperture jitter is added to the sampling instants.

Parameters:

  • data – Pointer to output array for waveform samples.

  • size – Number of samples to generate.

  • fs – Sample rate in Hz.

  • ampl – Amplitude.

  • freq – Signal frequency in Hz.

  • phase – Phase offset in radians.

  • td – Time delay (offset) in seconds.

  • tj – RMS aperture jitter in seconds (0 for no jitter).

void gaussian(real_t *data, size_t size, real_t mean, real_t sd)

Generate Gaussian (normally distributed) random samples.

If sd is 0, all samples are set to the mean value.

Parameters:

  • data – Pointer to output array for random samples.

  • size – Number of samples to generate.

  • mean – Mean of the distribution.

  • sd – Standard deviation of the distribution (0 for constant output).

void ramp(real_t *data, size_t size, real_t start, real_t stop, real_t noise)

Generate a linear ramp waveform from start to stop.

The ramp uses midpoint sampling within each step. If noise is greater than zero, Gaussian noise with the given RMS level is added.

Parameters:

  • data – Pointer to output array for waveform samples.

  • size – Number of samples to generate.

  • start – Starting value of the ramp.

  • stop – Ending value of the ramp.

  • noise – RMS level of additive Gaussian noise (0 for no noise).

void sin(real_t *data, size_t size, real_t fs, real_t ampl, real_t freq, real_t phase, real_t td, real_t tj)

Generate a sine waveform.

Computes data[i] = ampl * sin(2*pi*freq*(i/fs + td) + phase). If tj is greater than zero, Gaussian aperture jitter is added to the sampling instants.

Parameters:

  • data – Pointer to output array for waveform samples.

  • size – Number of samples to generate.

  • fs – Sample rate in Hz.

  • ampl – Amplitude.

  • freq – Signal frequency in Hz.

  • phase – Phase offset in radians.

  • td – Time delay (offset) in seconds.

  • tj – RMS aperture jitter in seconds (0 for no jitter).

template<typename T>
std::map<str_t, real_t> wf_analysis(const T *wf_data, size_t wf_size)

Compute time-domain statistics of a waveform.

Results include min, max, mid, range, average, RMS, AC RMS (DC-removed), and indices of min/max values.

Template Parameters:

T – Sample type (integer or floating-point).

Parameters:

  • wf_data – Pointer to waveform data.

  • wf_size – Number of elements in wf_data.

Returns:

Map of metric names to values.

const std::vector<str_t> &wf_analysis_ordered_keys()

Return the ordered list of result keys for wf_analysis().

Returns:

Reference to a vector of key strings in canonical order.