Crate comnum_math 

comnum-math — numerical methods without communication semantics

Special functions, quadrature, FFT plans, nearest-point search and the split-step solver of the nonlinear Schrödinger equation. Nothing here knows what a symbol or a channel is: the crates above give these methods their meaning.

Contents

Module	Content
fft	cached FFT plans with the NumPy conventions, fftfreq
geometry	vectors of the three-dimensional space: scalar product, norm, direction
linalg	QR, Cholesky, Hermitian systems and the SVD of small complex matrices
nearest	nearest::Slicer, the nearest point of a finite set
special	special functions: the error function, the Gaussian tail, Fresnel, Bessel, gamma, the exponential integral
quadrature	Simpson’s rule, the Gauss–Hermite and Gauss–Legendre rules
log_domain	ln(1 + e^x), max* and the log-sum-exp without overflow
stats	the moments of order two and four of a complex sequence, the normalised correlation of two
nlse	the symmetric split-step Fourier solvers of the scalar NLSE and of the Manakov equation
gf2	polynomials and matrices over GF(2)
gf2m	the Galois fields $\mathrm{GF}(2^{m})$ of the BCH and Reed–Solomon codes
bigint	unsigned integers of arbitrary size, for enumerative coding
bits	the Gray code gray, gray_inverse, and the conversions bits_to_index, index_to_bits (most significant bit first)
search	bisect, golden_max, argmax and gcd
sequences	linear-feedback shift registers and the Gold sequence of 3GPP

At the root (the functions of special, quadrature and log_domain are re-exported there):

• the log domain: log_sum_exp (ln Σ e^{v_i}), ln_1p_exp (ln(1 + e^x)), max_star (ln(e^a + e^b)), all without overflow;
• C64: the complex type of every signal (num_complex::Complex<f64>), and cis, e^{jθ};
• decibels: db2lin, lin2db (power ratios), db2amp, amp2db (amplitude ratios), dbm2w, w2dbm, db2np, np2db (attenuation per unit length), defined once in comnum_core::units next to the unit newtypes and re-exported here;
• sinc, sin(πx)/(πx), diric, the periodic sinc sin(nx/2)/(n sin(x/2)), and effective_length, (1 - e^{-αL})/α;
• special functions: erf, erfc, erfcinv, qfunc (the Gaussian tail Q(x) = ½ erfc(x/√2)), its inverse qfuncinv, fresnel (the Fresnel integrals $C$ and $S$), bessel_j0, bessel_i0e, bessel_k and ln_bessel_k, ln_gamma, gamma_p (the regularized incomplete gamma function), expint_e1 (the exponential integral);
• entropy, $-\sum_{i} p_{i} \log_{2} p_{i}$;
• signal statistics: power (mean |x|²), energy, papr_db;
• quadrature: simpson, try_simpson and simpson_weight (composite Simpson’s rule), gauss_hermite (∫ f(t) e^{-t²} dt) and gauss_legendre (∫_{-1}^{1} f(t) dt);
• physical constants PLANCK, BOLTZMANN, ELEMENTARY_CHARGE, SPEED_OF_LIGHT, and ZERO_CELSIUS, the origin of the Celsius scale in kelvin.

Examples

use comnum_math::*;
assert!((db2lin(3.0) - 1.9953).abs() < 1e-4);
assert!((dbm2w(0.0) - 1e-3).abs() < 1e-15);
assert!((qfunc(0.0) - 0.5).abs() < 1e-7);
let z = cis(std::f64::consts::FRAC_PI_2);
assert!((z - C64::new(0.0, 1.0)).norm() < 1e-15);

Re-exports

pub use bits::bits_to_index;

pub use bits::gray;

pub use bits::gray_inverse;

pub use bits::index_to_bits;

pub use log_domain::ln_1p_exp;

pub use log_domain::log_sum_exp;

pub use log_domain::log_sum_exp_iter;

pub use log_domain::max_star;

pub use quadrature::gauss_chebyshev;

pub use quadrature::gauss_hermite;

pub use quadrature::gauss_legendre;

pub use quadrature::gaussian_nodes;

pub use quadrature::simpson;

pub use quadrature::simpson_weight;

pub use quadrature::try_simpson;

pub use search::argmax;

pub use search::bisect;

pub use search::gcd;

pub use search::golden_max;

pub use special::bessel_i0e;

pub use special::bessel_j0;

pub use special::bessel_k;

pub use special::beta_inc;

pub use special::beta_inv;

pub use special::erf;

pub use special::erfc;

pub use special::erfcinv;

pub use special::expint_e1;

pub use special::fresnel;

pub use special::gamma_p;

pub use special::hermite_h;

pub use special::hyp1f2;

pub use special::ln_bessel_k;

pub use special::ln_binomial_pmf;

pub use special::ln_gamma;

pub use special::normal_pdf;

pub use special::qfunc;

pub use special::qfuncinv;

Modules

bigint

Unsigned integers of arbitrary size, with the few operations that enumerative coding needs: products and exact quotients by machine integers, sums, differences, comparisons, and conversions from and to bit strings.

bits

Integers as bit strings: the reflected binary Gray code and the conversions between an index and its bits, most significant bit first.

fft

FFT plans with the NumPy conventions.

geometry

Vectors of the three-dimensional Euclidean space, as [f64; 3]: the scalar product, the difference, the norm and the direction of a vector, and the unit vector of spherical angles.

gf2

Arithmetic over GF(2): binary polynomials and dense binary matrices on bitsets.

gf2m

The Galois fields $\mathrm{GF}(2^{m})$: the arithmetic on which comnum_fec builds the BCH and Reed–Solomon codes.

linalg

Dense complex linear algebra for the small matrices of MIMO processing.

log_domain

The log domain of probabilities and LLRs, without overflow: ln_1p_exp, max_star and its choice Jacobian (of comnum-core), log_sum_exp and log_sum_exp_iter (re-exported at the root).

nearest

Nearest-point search in a finite set of complex points.

nlse

The symmetric split-step Fourier solvers of the nonlinear Schrödinger equation: scalar (SplitStep, SplitStepF32, both built from the Steps of a span) and dual-polarisation Manakov (ManakovSplitStep).

quadrature

Quadrature: the composite Simpson rule (simpson, try_simpson, simpson_weight) and the Gauss rules (gauss_hermite, gauss_legendre, and gaussian_nodes, the nodes of a Gaussian expectation), re-exported at the root.

search

One-dimensional searches: bisection, regula falsi and golden-section maximisation, the largest element of a sequence, and the greatest common divisor.

sequences

Binary pseudo-random sequences (linear-feedback shift registers, the length-31 Gold sequence of 3GPP) and the Zadoff–Chu sequences.

special

Special functions: the error function and its inverse, the Gaussian tail, the Fresnel integrals, Bessel functions, the gamma function and the regularized incomplete gamma function, the binomial law, the regularized incomplete beta function and its inverse, the exponential integral, the generalized hypergeometric function ${1}F{2}$ and the Hermite polynomials (all re-exported at the root).

stats

Second- and fourth-order statistics of complex sequences.

Enums

Jacobian

The Jacobian logarithm, exact or max-log: defined in comnum-core, since the soft demapper trait comnum_core::traits::Demap takes it, and re-exported here for max_star, the BCJR and turbo decoders of comnum-fec and the demappers of comnum-mapping. The Jacobian logarithm of the log-MAP algorithms and of the soft demappers, exact or approximated by its maximum:

Constants

BOLTZMANN

Boltzmann constant (J/K).

ELEMENTARY_CHARGE

Elementary charge (C).

PLANCK

Planck constant (J·s).

SPEED_OF_LIGHT

Speed of light in vacuum (m/s).

ZERO_CELSIUS

The temperature of 0 °C (K): $T_{\mathrm{K}} = T_{\mathrm{°C}} + 273.15$.

Functions

amp2db

Linear amplitude ratio to dB: 20 log10(x).

cis

e^{jθ} = cos θ + j sin θ.

db2amp

Amplitude ratio in dB to linear: 10^{x/20}.

db2lin

Power ratio in dB to linear: 10^{x/10}.

db2np

Attenuation in dB per unit length to nepers (power): α_dB / (10 log10 e).

dbm2w

Power in dBm to watts: 10^{P/10} · 1 mW.

diric

The Dirichlet (periodic sinc) function of MATLAB, $\operatorname{diric}(x, n) = \frac{\sin(n x/2)}{n \sin(x/2)}$, of period $2\pi$ ($4\pi$) for odd (even) $n$, with its limits $(-1)^{k(n-1)}$ at $x = 2\pi k$; $\sin(n\theta)/\sin\theta = n \operatorname{diric}(2\theta, n)$ is the array factor of $n$ equally spaced terms.

effective_length

The effective length (1 - e^{-αL})/α of an attenuation α over length (L itself when αL is negligible).

energy

Energy Σ |x_n|² of a complex signal.

entropy

The entropy (bits) of a distribution, the zero probabilities left out:

lin2db

Linear power ratio to dB: 10 log10(x).

nm2hz

The frequency $f = c / \lambda$ (Hz) of the vacuum wavelength wavelength_nm (nm), $c$ the SPEED_OF_LIGHT.

np2db

Attenuation in nepers (power) per unit length to dB: 10 log10(e) · α.

papr_db

Peak-to-average power ratio max|x|² / mean|x|² in dB (-inf for an empty or zero block).

power

Mean power (1/N) Σ |x_n|² of a complex signal (0 for an empty slice).

sinc

The normalised sinc sin(πx)/(πx), 1 at 0.

w2dbm

Power in watts to dBm.

Type Aliases

C64

Complex number with f64 components (the type of every complex sample).