NumericAL
A header-only C++20 lexer built on REAL
Loading...
Searching...
No Matches
Namespaces | Classes | Concepts | Typedefs | Enumerations | Functions | Variables
numerical Namespace Reference

The NumericAL public API. More...

Namespaces

namespace  blas
 
namespace  detail
 

Classes

class  argument_error
 Thrown when an argument is outside what an operation takes (a tolerance below 0, an FFT type past 4). More...
 
struct  balanced_matrix
 A matrix balanced, B = T⁻¹ A T with T = P D (matrix_balance). More...
 
struct  band_tridiagonal_form
 A symmetric or Hermitian band matrix's tridiagonal form: A = W T Wᴴ, T real symmetric tridiagonal of diagonal d and off-diagonal e (none negative), W unitary (where asked; else empty). More...
 
class  cholesky_decomposition
 A Cholesky factorisation A = L Lᴴ of a Hermitian positive-definite matrix. More...
 
struct  conditioned_solution
 A solution and the reciprocal condition number of its system (solve_banded_conditioned). More...
 
class  convergence_error
 Thrown when an iterative algorithm has not converged within its bound of sweeps. More...
 
class  dimension_error
 Thrown when an operation's operands have incompatible shapes. More...
 
class  eigen_decomposition
 The eigenvalues, and optionally the right eigenvectors, of a general square matrix, as numpy.linalg.eig. More...
 
struct  eigen_subset
 Some eigenvalues of a Hermitian matrix and their eigenvectors (hermitian_eigen_subset). More...
 
class  einsum_error
 Thrown when an einsum specification is malformed or inconsistent. More...
 
class  error
 What every exception NumericAL throws is, beside its standard base (all but std::bad_alloc and std::system_error, the allocator's and the system's): catch (const numerical::error&) catches each of them, and catch (const std::domain_error&) (its standard base) still catches a non_finite_error. Not a std::exception itself, so that each keeps the standard base it has; what gives the message. More...
 
struct  funm_plan
 Where funm wants f, and the forms it completes: a Hermitian A's eigendecomposition (t Λ, z V); else its complex Schur form (a real matrix's real form made complex, as rsf2csf), reordered so the eigenvalues within 10⁻² of the largest modulus (or of 1) gather in runs. points: the eigenvalues in the form's order, then detail::contour_points on the circle about each run of two or more. More...
 
struct  funm_result
 A function of a square matrix from its complex Schur form, as scipy.linalg.funm forms it: f(A) and the estimate of its relative error. More...
 
class  generalized_schur
 The generalized Schur decomposition of a complex pencil A − λ B, A = Q S Zᴴ and B = Q T Zᴴ, as scipy.linalg.qz(a, b, output="complex") (LAPACK's zgges): Q and Z unitary, S and T upper triangular, T's diagonal real and non-negative; the generalized eigenvalues α_k / β_k on the diagonals (β_k = 0 an infinite one). Reordered as scipy.linalg.ordqz by sort or reorder. Each operand is first brought into the range [√safmin / ε, ε / √safmin] of its largest magnitude where it lies outside, as zgges scales it, and the form and the eigenvalues taken back. More...
 
class  hermitian_eigen
 The eigenvalues and eigenvectors of a complex Hermitian matrix. More...
 
class  index_error
 Thrown when an index or a range leaves its axis. More...
 
class  ldl_decomposition
 The symmetric indefinite factorisation of a symmetric or Hermitian matrix, as scipy.linalg.ldl: A = L D Lᴴ (Hermitian) or A = L D Lᵀ (symmetric), Bunch and Kaufman's diagonal pivoting (LAPACK's sytrf, hetrf: by panels of 64 columns from order 384, their trailing update one matrix product; the unblocked sytf2, hetf2 below it and for the last columns) on the lower triangle, or on the upper one (lower = false, L then upper triangular); D block diagonal with blocks of order 1 and 2; L with a unit diagonal once its rows are permuted (permutation), as SciPy returns them. More...
 
struct  least_squares_solution
 A least-squares solution and what numpy.linalg.lstsq reports beside it (least_squares). More...
 
struct  logm_result
 The principal logarithm of a square matrix with what SciPy warns of: log A (complex), and whether A's triangular form was exactly singular (its zero diagonal entries taken as 10⁻²⁰, as SciPy's) or nearly (a diagonal entry below 10⁻²⁰ in modulus). More...
 
class  lu_decomposition
 An LU factorisation with partial pivoting of a square matrix: each column's pivot the first entry of the largest detail::pivot_magnitude below the diagonal, |Re| + |Im| of a complex one, as LAPACK's. More...
 
class  matrix
 A dense, row-major matrix of T with value semantics. More...
 
class  negative_power_error
 Thrown when an integer is raised to a negative integer power, as NumPy refuses it: no integer is the answer. More...
 
class  no_real_root_error
 Thrown when a real matrix has no real principal square root (a real eigenvalue below 0): its root is complex. More...
 
class  non_finite_error
 Thrown when a decomposition's input holds an infinite or NaN entry: no factorisation of it means anything, and the iterative ones (eigh, SVD) would stop at once and return plausible values. More...
 
class  not_positive_definite_error
 Thrown when a Cholesky factorisation finds the matrix not positive-definite. More...
 
class  pivoted_qr_decomposition
 A QR factorisation with column pivoting A P = Q R of an m × n matrix, as scipy.linalg.qr(a, pivoting=True) (LAPACK's geqp3): at each step the column of largest remaining norm moved first, so R's diagonal does not grow in modulus down the diagonal and reveals A's numerical rank; the norms downdated as LAPACK's laqp2 downdates them, recomputed where the downdate has lost too much (√ε). Householder reflectors as larfg forms them; R's diagonal then made real and non-negative, as qr_decomposition's (Q's columns taking the phases), where LAPACK's may be negative. More...
 
class  qr_decomposition
 A QR factorisation A = Q R of an m × n matrix, as NumPy's qr, reduced by default. More...
 
class  rank_cutoff
 The magnitude at or under which a singular value counts as zero, in a rank (matrix_rank), a pseudo-inverse (pinv) or a least-squares solution (lstsq): by default NumPy's, the largest singular value times the machine epsilon times the larger dimension; relative to the largest, as NumPy's rcond and rtol; or absolute, as matrix_rank's tol. More...
 
class  real_generalized_schur
 The generalized real Schur decomposition of a real pencil A − λ B, A = Q S Zᵀ and B = Q T Zᵀ, as scipy.linalg.qz(a, b) (LAPACK's dgges): Q and Z orthogonal, T upper triangular with a non-negative diagonal, S quasi-triangular, a 2 × 2 diagonal block for each conjugate pair of eigenvalues, T diagonal and positive there; the eigenvalues (αr + i αi) / β (β = 0 an infinite one). More...
 
struct  rectangular_lu
 The pivoted LU factorisation of an m × n matrix (lu_factors): A = P L U. More...
 
class  schur_decomposition
 The Schur decomposition A = Z T Zᴴ of a square matrix, as scipy.linalg.schur (LAPACK's dgees/zgees): Z orthogonal (unitary), T upper quasi-triangular for a real A (a complex pair a 2 × 2 block in standard form, its diagonal equal, its off-diagonal of opposite signs), upper triangular for a complex one; T's diagonal (and blocks) holds the eigenvalues. Eigenvalues isolated first by permutations (detail::isolate, dgees's ‘dgebal('P’)), which keepZorthogonal and leave a triangular or block-triangular part no iteration; no diagonal scaling, which would not. \tparam Tdoubleorstd::complex<double>`. More...
 
class  singular_matrix_error
 Thrown when a matrix has no unique solution (it is singular). More...
 
class  svd_decomposition
 The singular value decomposition A = U Σ Vᴴ of an m × n matrix. More...
 
class  symmetric_eigen
 The eigenvalues and eigenvectors of a real symmetric matrix. More...
 
class  tensor
 A dense N-dimensional tensor of T with value semantics, read row-major. Its elements are immutable once built, so tensors share them: a copy, a tensor of another shape over the same elements (reshaped), one with its axes permuted (transposed) and a slice of them (sliced), views reading them along other strides, hold the one buffer, freed with the last of them. A view's elements in row-major order (data) are copied out on first need, once, and shared with the view's copies. More...
 
class  vector
 A dense vector of T with value semantics. More...
 

Concepts

concept  field
 A floating-point field: float, double, long double, or std::complex of one. The factorisations and the solvers require it, so that an integer matrix is refused at compile time, by name, where it would otherwise be factorised in integer division.
 
concept  double_field
 double or std::complex<double>: the scalars of the decompositions written for those alone (the eigendecompositions, the Schur form, the pivoted QR, LDLᴴ), which refuse any other at compile time by this name.
 

Typedefs

template<typename T >
using buffer = std::vector< T, detail::default_init_allocator< T > >
 The storage of vector, matrix and tensor, namely a std::vector whose buffer<T>(n) and resize(n) leave a double or a complex number uninitialised, for a result about to be written in full. buffer<T>(n, T {}) zeroes, as std::vector<T>(n) does.
 

Enumerations

enum class  triangular_op : unsigned char { none , transpose , adjoint }
 How solve_triangular reads its matrix: as it lies, transposed, or conjugate-transposed (SciPy's trans 0, 1 and 2). More...
 
enum class  qr_mode { reduced , complete }
 The factors a numerical::qr_decomposition keeps, as numpy.linalg.qr's modes name them. More...
 
enum class  eigen_method { tridiagonal_ql , jacobi , divide_and_conquer }
 How numerical::symmetric_eigen diagonalises. More...
 
enum class  fft_norm : unsigned char { backward , ortho , forward }
 How a transform and its inverse are scaled, as NumPy's norm. More...
 
enum class  gemm_path : std::uint8_t {
  portable = 0 , neon = 1 , avx2 = 2 , avx512 = 3 ,
  amx = 4
}
 The kernels a double matrix product can run on (a float one too on arm64), from the most portable. Each is used only where the processor has it: NEON on every arm64 chip, the AVX ones where cpuid reports them, the Apple AMX on an M1 to M4 chip whose self-test passes (see x86.hpp and amx.hpp). More...
 
enum class  frechet_method { scaling_pade_squaring , block_enlarge }
 How expm_frechet computes: Al-Mohy and Higham's algorithm (SciPy's "SPS"), or the exponential of the block matrix [[A, E], [0, A]] ("blockEnlarge"). More...
 
enum class  svd_method { bidiagonal_qr , jacobi , divide_and_conquer }
 How numerical::svd_decomposition computes the decomposition of R, after a Householder QR. More...
 
enum class  take_mode : unsigned char { raise , wrap , clip }
 What take does with an index outside its axis, as numpy.take's mode: refuse it, take it modulo the extent, or take the nearer end. More...
 

Functions

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > solve_banded (std::size_t lower, std::size_t upper, const matrix< T > &ab, const matrix< T > &b)
 The solution X of A X = B for the n × n band A of lower subdiagonals and upper superdiagonals, given as scipy.linalg.solve_banded takes it: ab of lower + upper + 1 rows and n columns, ab[upper + i − j][j] = A(i, j) (its corners, outside the matrix, not read). By the LU factorisation with partial pivoting in LAPACK's band storage (gbsv): O(n · lower · (lower + upper)) operations; one sub- and one superdiagonal by detail::tridiagonal_solve (gtsv), as SciPy.
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
conditioned_solution< T > solve_banded_conditioned (std::size_t lower, std::size_t upper, const matrix< T > &ab, const matrix< T > &b)
 solve_banded with the reciprocal condition number of the band, as scipy.linalg.solve takes them from LAPACK's gbsv and gbcon: the band's LU factorisation for any band (gtsv's partial pivoting for three diagonals), ‖A‖₁ its largest column sum of moduli, ‖A⁻¹‖₁ estimated from the factors (Hager's method, a few solves of O(n (lower + upper)) each), so within a small factor of the exact.
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > solveh_banded (const matrix< T > &ab, const matrix< T > &b, bool lower_form=false)
 The solution X of A X = B for the Hermitian positive-definite band A, given as scipy.linalg.solveh_banded takes it: ab of kd + 1 rows and n columns, its upper form ab[kd + i − j][j] = A(i, j) for i ≤ j or, lower_form, its lower ab[i − j][j] = A(i, j) for i ≥ j (the diagonal's imaginary part, and the corners, not read). By the band's Cholesky factor (LAPACK's pbsv); one off-diagonal by detail::positive_tridiagonal_solve (ptsv), as SciPy.
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > cholesky_banded (const matrix< T > &ab, bool lower_form=false)
 The Cholesky factor of the Hermitian positive-definite band ab, as scipy.linalg.cholesky_banded (LAPACK's pbtrf): in ab's own form, U (A = Uᴴ U) in the upper one, L = Uᴴ (A = L Lᴴ) with lower_form, the corners outside the band as ab has them.
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > cho_solve_banded (const matrix< T > &cb, const matrix< T > &b, bool lower_form=false)
 The solution X of A X = B from cholesky_banded's factor cb of A, as scipy.linalg.cho_solve_banded((cb, lower_form), b) (LAPACK's pbtrs).
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > solve_toeplitz (const vector< T > &c, const vector< T > &r, const matrix< T > &b)
 The solution X of T X = B for the n × n Toeplitz T of first column c and first row r (T(i, j) = c[i − j] for i ≥ j, r[j − i] above; r[0] not read), as scipy.linalg.solve_toeplitz: Levinson's recursion as Numerical Recipes' toeplz (which SciPy's follows), every right-hand side at once, O(n²) operations a column: the solutions of the leading principal systems grown by one row at a time, the forward and backward vectors g and h beside them. It needs every leading principal minor nonsingular (not only T), and like all Levinson recursions it is stable for a well-conditioned symmetric positive definite T and may lose accuracy otherwise.
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > solve_circulant (const vector< T > &c, const matrix< T > &b, bool least_squares=false, std::optional< double > tol=std::nullopt)
 The solution X of C X = B for the n × n circulant C of first column c (C(i, j) = c[(i − j) mod n]), as scipy.linalg.solve_circulant: the Fourier transform diagonalises it, X = F⁻¹ (F B / F c), O(n log n) a column. An eigenvalue F c of modulus at most tol (by default n ε max |F c|, as numpy.linalg.matrix_rank judges) makes C near singular: refused, or with least_squares its terms left out (the minimum-norm least-squares solution, SciPy's singular="lstsq"). Real c and b give a real X (the transform's real part, as SciPy's).
 
template<typename T >
matrix< T > toeplitz (const vector< T > &c, const vector< T > &r)
 The m × n Toeplitz matrix of first column c (m entries) and first row r (n), as scipy.linalg.toeplitz: T(i, j) = c[i − j] for i ≥ j, r[j − i] above (r[0] not read).
 
template<typename T >
matrix< T > circulant (const vector< T > &c)
 The n × n circulant matrix of first column c, as scipy.linalg.circulant: C(i, j) = c[(i − j) mod n].
 
template<typename T >
matrix< T > hankel (const vector< T > &c, const vector< T > &r)
 The m × n Hankel matrix of first column c (m entries) and last row r (n), as scipy.linalg.hankel: H(i, j) = c[i + j] while i + j < m, r[i + j − m + 1] past it (r[0] not read).
 
template<typename T >
matrix< T > block_diag (const std::vector< matrix< T > > &blocks)
 The block diagonal matrix of blocks, in order, as scipy.linalg.block_diag: zeros off the blocks.
 
template<typename T >
balanced_matrix< T > matrix_balance (const matrix< T > &a, bool permute=true, bool scale=true)
 The square a balanced, as scipy.linalg.matrix_balance(a, permute, scale, separate=True) (LAPACK's dgebal): B = T⁻¹ A T, T = P D a permutation (permute: rows and columns isolating an eigenvalue moved to the ends) times powers of two (scale: the remaining block's rows and columns brought within a factor of 2 of each other in norm), so every entry of B is an entry of A scaled exactly.
 
template<field T>
vector< std::complex< double > > eigenvalues (const matrix< T > &a)
 The eigenvalues alone of the square a, as numpy.linalg.eigvals.
 
template<typename T >
band_tridiagonal_form< T > band_tridiagonal (const matrix< T > &lower, bool basis)
 Reduces the real symmetric or complex Hermitian band matrix whose lower form is lower ((u + 1) × n, entry (d, j) the matrix's (j + d, j)) to a real symmetric tridiagonal one, as LAPACK's dsbtrd and zhbtrd: each column's entries below the first subdiagonal annihilated by plane rotations, from the farthest in, each rotation's bulge chased down the band by u rows at a time, in n² u operations; then the off-diagonal made real and non-negative by a diagonal of phases. With basis, the rotations' product (and the phases), W, so that the eigenvectors of A are W times those of T.
 
template<field T>
vector< T > solve (matrix< T > a, const vector< T > &b)
 Solves the linear system A x = b for a square A.
 
template<field T>
matrix< T > solve (matrix< T > a, const matrix< T > &b)
 Solves A X = B for a square A and every column of B at once, as numpy.linalg.solve with a matrix right-hand side: one factorisation of A, then one substitution per column.
 
template<field T>
T determinant (matrix< T > a)
 The determinant of a square matrix.
 
template<field T>
matrix< T > inverse (matrix< T > a)
 The inverse of a square matrix.
 
template<field T>
double triangular_reciprocal_condition (const matrix< T > &a, bool lower)
 The reciprocal condition number 1 / (‖A‖₁ ‖A⁻¹‖₁) of a triangular matrix, as LAPACK's trcon (1-norm): its lower triangle or its upper one read, the other never; ‖A⁻¹‖₁ estimated by substitutions (Hager's method), so within a small factor of the exact.
 
template<field T>
matrix< T > solve_triangular (const matrix< T > &a, matrix< T > b, bool lower, triangular_op op=triangular_op::none, bool unit_diagonal=false)
 Solves A X = B, Aᵀ X = B or Aᴴ X = B (op) for a triangular A, as scipy.linalg.solve_triangular: its lower triangle or its upper one is read, the other never, and its diagonal as ones where unit_diagonal. By substitution, a block's rows by rows of terms and the rows past it through the matrix product kernel: n² k multiply-adds, where solve factorises A first.
 
template<field T>
vector< T > solve_triangular (const matrix< T > &a, const vector< T > &b, bool lower, triangular_op op=triangular_op::none, bool unit_diagonal=false)
 solve_triangular of one right-hand side.
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
rectangular_lu< T > lu_factors (const matrix< T > &a)
 The pivoted LU factorisation A = P L U of an m × n matrix, as scipy.linalg.lu: L m × k lower trapezoidal with a unit diagonal, U k × n upper trapezoidal, k = min(m, n), rows chosen by partial pivoting. A wide matrix's square part by lu_decomposition and U's other columns by L⁻¹ P A (a triangular solve); a tall one by lu_decomposition of it beside zero columns (its first n columns factorised alike) up to detail::lu_tall_ratio times as tall as wide, by dgetrf2's recursion over its columns (detail::tall_lu_columns) past. A zero pivot leaves its column of L zero, as LAPACK's.
 
template<field T>
cholesky_decomposition< T > cholesky (matrix< T > a)
 Cholesky-factorises a Hermitian positive-definite matrix.
 
template<typename T >
qr_decomposition< T > qr (const matrix< T > &a)
 QR-factorises an m × n matrix.
 
template<typename T >
matrix< T > qr_r (matrix< T > a)
 The factor R of the QR decomposition of an m × n matrix, k × n, k = min(m, n): qr_decomposition's R to the bit, Q never formed.
 
template<detail::fft_input T>
requires detail::split_complex<T>
tensor< T > fft (const tensor< T > &a, std::optional< std::size_t > n=std::nullopt, std::ptrdiff_t axis=-1, fft_norm norm=fft_norm::backward)
 The discrete Fourier transform of a along axis, as numpy.fft.fft: X_k = Σ_j x_j e^{−2πi jk/n}.
 
template<std::floating_point T>
tensor< std::complex< T > > fft (const tensor< T > &a, std::optional< std::size_t > n=std::nullopt, std::ptrdiff_t axis=-1, fft_norm norm=fft_norm::backward)
 The discrete Fourier transform of real a along axis, as numpy.fft.fft of a real array: its non-negative frequencies by the real transform (rfft's), the others by their Hermitian symmetry, X_{n−k} = conj X_k exactly; a length whose complex transform takes four steps (four_step_plan) as a complex one, on the threads.
 
template<detail::fft_input T>
requires detail::split_complex<T>
tensor< T > ifft (const tensor< T > &a, std::optional< std::size_t > n=std::nullopt, std::ptrdiff_t axis=-1, fft_norm norm=fft_norm::backward)
 The inverse discrete Fourier transform of a along axis, as numpy.fft.ifft: x_j = (1/n) Σ_k X_k e^{2πi jk/n} with the default norm.
 
template<std::floating_point T>
tensor< std::complex< T > > ifft (const tensor< T > &a, std::optional< std::size_t > n=std::nullopt, std::ptrdiff_t axis=-1, fft_norm norm=fft_norm::backward)
 The inverse discrete Fourier transform of real a along axis, as numpy.fft.ifft of a real array: the conjugate of its transform (fft of a real tensor), scaled as the inverse.
 
template<typename T >
tensor< T > fftshift (const tensor< T > &a, const std::vector< std::ptrdiff_t > &axes, bool inverse=false)
 a with its axes axes rolled so that each one's element 0 lands at its middle, as numpy.fft.fftshift: element j of each to (j + n/2) mod n, an axis given twice rolled twice; or back, as numpy.fft.ifftshift, where inverse. In one copy, whatever the axes.
 
template<typename T >
tensor< T > fftshift (const tensor< T > &a, std::ptrdiff_t axis=-1, bool inverse=false)
 a with its axis axis rolled so that its element 0 lands at its middle, as numpy.fft.fftshift along one axis: element j to (j + n/2) mod n; or back, as numpy.fft.ifftshift, where inverse.
 
template<std::floating_point T>
tensor< std::complex< T > > rfft (const tensor< T > &a, std::optional< std::size_t > n=std::nullopt, std::ptrdiff_t axis=-1, fft_norm norm=fft_norm::backward)
 The discrete Fourier transform of real a along axis, its n/2 + 1 non-negative frequencies, as numpy.fft.rfft. An even n by the complex transform of its n/2 pairs and their recombination, an odd one by the complex transform of its points.
 
template<std::floating_point T>
tensor< T > irfft (const tensor< std::complex< T > > &a, std::optional< std::size_t > n=std::nullopt, std::ptrdiff_t axis=-1, fft_norm norm=fft_norm::backward)
 The inverse of rfft along axis, as numpy.fft.irfft: n real points from the first n/2 + 1 frequencies of a (cut, or padded with zeros), the imaginary parts of the zero frequency and of an even n's last read as 0.
 
constexpr fft_norm swapped (fft_norm norm) noexcept
 norm with its forward and backward exchanged, as NumPy's hfft and ihfft take it.
 
template<std::floating_point T>
tensor< T > hfft (const tensor< std::complex< T > > &a, std::optional< std::size_t > n=std::nullopt, std::ptrdiff_t axis=-1, fft_norm norm=fft_norm::backward)
 The transform of a signal of Hermitian symmetry, its n real points from the non-negative frequencies a, as numpy.fft.hfft: irfft of conj(a), its scaling's direction exchanged.
 
template<std::floating_point T>
tensor< std::complex< T > > ihfft (const tensor< T > &a, std::optional< std::size_t > n=std::nullopt, std::ptrdiff_t axis=-1, fft_norm norm=fft_norm::backward)
 The inverse of hfft, as numpy.fft.ihfft: conj(rfft(a)), its scaling's direction exchanged.
 
template<std::floating_point T>
tensor< T > dct (const tensor< T > &a, int type=2, std::optional< std::size_t > n=std::nullopt, std::ptrdiff_t axis=-1, fft_norm norm=fft_norm::backward, std::optional< bool > orthogonalize=std::nullopt)
 The discrete cosine transform of real a along axis, as scipy.fft.dct: type 2 by default, y_k = 2 Σ_j x_j cos(πk(2j + 1)/2n); type 1 x_0 + (−1)^k x_{n−1} + 2 Σ_{0<j<n−1} x_j cos(πjk/(n − 1)); type 3 x_0 + 2 Σ_{j>0} x_j cos(πj(2k + 1)/2n); type 4 2 Σ_j x_j cos(π(2j + 1)(2k + 1)/4n). By a Fourier transform of n points (2(n − 1) for type 1).
 
template<std::floating_point T>
tensor< T > idct (const tensor< T > &a, int type=2, std::optional< std::size_t > n=std::nullopt, std::ptrdiff_t axis=-1, fft_norm norm=fft_norm::backward, std::optional< bool > orthogonalize=std::nullopt)
 The inverse of dct of the same type, as scipy.fft.idct: the transform of type 3 for type 2 and of type 2 for type 3 (types 1 and 4 their own), scaled by 1/2n (1/2(n − 1) for type 1) by default.
 
template<std::floating_point T>
tensor< T > dst (const tensor< T > &a, int type=2, std::optional< std::size_t > n=std::nullopt, std::ptrdiff_t axis=-1, fft_norm norm=fft_norm::backward, std::optional< bool > orthogonalize=std::nullopt)
 The discrete sine transform of real a along axis, as scipy.fft.dst: type 2 by default, y_k = 2 Σ_j x_j sin(π(k + 1)(2j + 1)/2n); type 1 2 Σ_j x_j sin(π(j + 1)(k + 1)/(n + 1)); type 3 (−1)^k x_{n−1} + 2 Σ_{j<n−1} x_j sin(π(j + 1)(2k + 1)/2n); type 4 2 Σ_j x_j sin(π(2j + 1)(2k + 1)/4n). Type 1 by a real Fourier transform of 2(n + 1) points, the others by dct's.
 
template<std::floating_point T>
tensor< T > idst (const tensor< T > &a, int type=2, std::optional< std::size_t > n=std::nullopt, std::ptrdiff_t axis=-1, fft_norm norm=fft_norm::backward, std::optional< bool > orthogonalize=std::nullopt)
 The inverse of dst of the same type, as scipy.fft.idst: the transform of type 3 for type 2 and of type 2 for type 3 (types 1 and 4 their own), scaled by 1/2n (1/2(n + 1) for type 1) by default.
 
gemm_path limit_gemm_path (gemm_path most) noexcept
 Keeps double matrix products on most or a more portable path: the most capable path at or below it that can run here. gemm_path::amx restores the best one; gemm_path::portable keeps them on the compiler's own vectors, with no instruction chosen at run time. Paths below the cap are not probed.
 
gemm_path gemm_path_in_use () noexcept
 The path double matrix products take.
 
matrix< std::complex< double > > generalized_eigenvectors (const generalized_schur &d, bool left)
 The right (or, where left, the left) eigenvectors of the pencil d decomposes, as LAPACK's ztgevc and scipy.linalg.eig(a, b): for each eigenvalue (α, β) in the diagonals' order, x with (β S − α T) x = 0 and x_k = 1 by back substitution (yᴴ (β S − α T) = 0 forward for a left one), then Z x (Q y) made of unit 2-norm, as SciPy normalises ggev's; a diagonal entry of β S − α T below ε (|β| ‖S‖ + |α| ‖T‖) taken as that bound (ztgevc's SMIN, at least the smallest normal number), and an eigenvalue with α and β both zero (a singular pencil) given the unit vector of its place, as ztgevc gives it.
 
matrix< std::complex< double > > generalized_eigenvectors (const real_generalized_schur &d, bool left)
 The right (or, where left, the left) eigenvectors of the real pencil d decomposes, complex, as scipy.linalg.eig(a, b) gives them for a real pencil (each of unit 2-norm): each 2 × 2 block of S and T made triangular first by unitary rotations from both sides (the left one along T v, the right one along the block's eigenvector v), carried through S, T, Q and Z, then the complex pencil's vectors (generalized_eigenvectors). The columns in the diagonals' order, as d's values.
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > solve_continuous_are (const matrix< T > &a, const matrix< T > &b, const matrix< T > &q, const matrix< T > &r, const std::type_identity_t< matrix< T > > *e=nullptr, const std::type_identity_t< matrix< T > > *s=nullptr, bool balanced=true)
 The stabilising solution X of the continuous algebraic Riccati equation Aᴴ X E + Eᴴ X A − (Eᴴ X B + S) R⁻¹ (Bᴴ X E + Sᴴ) + Q = 0 (E = I and S = 0 when e and s are null), as scipy.linalg.solve_continuous_are: without e and with R well-conditioned (its condition below 1/√ε), the Schur form of the Hamiltonian [[Ã, −G], [−Q̃, −Ãᴴ]] (Laub, 1979, in real arithmetic for real operands); else, as SciPy, the eigenvalues of the extended Hamiltonian pencil in the left half-plane moved first in its generalized Schur form (generalized_schur), R never inverted. Then one step of Newton's method, kept where it lowers the residual.
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > solve_discrete_are (const matrix< T > &a, const matrix< T > &b, const matrix< T > &q, const matrix< T > &r, const std::type_identity_t< matrix< T > > *e=nullptr, const std::type_identity_t< matrix< T > > *s=nullptr, bool balanced=true)
 The stabilising solution X of the discrete algebraic Riccati equation Aᴴ X A − Eᴴ X E − (Aᴴ X B + S) (R + Bᴴ X B)⁻¹ (Bᴴ X A + Sᴴ) + Q = 0 (E = I and S = 0 when e and s are null), as scipy.linalg.solve_discrete_are: the eigenvalues of the extended symplectic pencil inside the unit circle moved first in its generalized Schur form (generalized_schur), nothing inverted.
 
template<typename T >
matrix< T > operator+ (const matrix< T > &a, const matrix< T > &b)
 Element-wise sum.
 
template<typename T >
matrix< T > operator- (const matrix< T > &a, const matrix< T > &b)
 Element-wise difference.
 
template<typename T >
matrix< T > operator* (const T &scalar, const matrix< T > &m)
 Scalar times matrix.
 
template<typename T >
matrix< T > operator* (const matrix< T > &m, const T &scalar)
 Matrix times scalar.
 
template<typename T >
vector< T > operator* (const matrix< T > &a, const vector< T > &v)
 Matrix–vector product: each element its row's dot product with v (detail::matrix_times_vector).
 
template<typename T >
matrix< T > operator* (const matrix< T > &a, const matrix< T > &b)
 Matrix–matrix product.
 
template<typename T >
matrix< T > transpose (const matrix< T > &m)
 The transpose, by blocks of transpose_tile (walked by detail::transpose_piece's pieces), the result's blocks of rows shared among the threads.
 
template<typename T >
bool approx_equal (const matrix< T > &a, const matrix< T > &b, double tolerance=1e-9)
 Element-wise closeness within a tolerance (for inexact scalars).
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > expm (const matrix< T > &a)
 The exponential e^A of a square matrix, as scipy.linalg.expm: scaling and squaring of a Padé approximant, as Al-Mohy and Higham's algorithm (2009): the degree 3, 5, 7, 9 or 13 and the squarings s chosen from ‖A^{2k}‖₁^{1/2k} (exact, A², A⁴ and A⁶ formed, A⁸ and A¹⁰ where needed) and the approximant's backward error bound (ℓ), then r(2⁻ˢ A) squared s times; an upper triangular A's diagonal and first superdiagonal written exactly at each squaring. A Hermitian A (to the bit) of order hermitian_expm_least or more: V e^Λ Vᴴ from its eigendecomposition.
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > expm_multiply (const matrix< T > &a, const matrix< T > &b, double t=1.0)
 e^{tA} B without forming e^{tA}, as scipy.sparse.linalg.expm_multiply: Al-Mohy and Higham's algorithm 3.2 (2011). A less μ I, μ its trace over n; then s steps, each m terms at most of the Taylor series of e^{tA/s} on the step's start, each term one product of A by the n × k block (the matrix product kernel), the series stopped where its last two terms fall under the unit roundoff of the sum; each step times e^{tμ/s}. m and s the least products for the unit roundoff (detail::plan_taylor), the norms of A's powers estimated through products with vectors (detail::one_norm_estimate). Some m s products of n² k where e^{tA} takes n³ several times: the few columns' case.
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > solve_sylvester (const matrix< T > &a, const matrix< T > &b, const matrix< T > &q)
 The solution X (m × n) of the Sylvester equation A X + X B = Q, as scipy.linalg.solve_sylvester: by Bartels and Stewart's method, the Schur forms A = U R Uᴴ and B = V S Vᴴ (schur_decomposition), R Y + Y S = Uᴴ Q V solved by blocks (LAPACK's trsyl), then X = U Y Vᴴ. Real throughout for real operands (R and S quasi-triangular), complex where any is. Where A and −B share an eigenvalue the equation has no unique solution: a pivot below the rounding of the forms is perturbed, as LAPACK's, and the answer grows accordingly.
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > solve_continuous_lyapunov (const matrix< T > &a, const matrix< T > &q)
 The solution X of the continuous Lyapunov equation A X + X Aᴴ = Q, as scipy.linalg.solve_continuous_lyapunov: one Schur form A = U R Uᴴ, whose adjoint Aᴴ = U Rᴴ Uᴴ it also gives (solve_sylvester with b = Aᴴ formed a second one, twice the time), then R Y + Y Rᴴ = Uᴴ Q U and X = U Y Uᴴ. Rᴴ is lower triangular: with J the order reversed, J Rᴴ J is upper (quasi-)triangular, so R (Y J) + (Y J)(J Rᴴ J) = (Uᴴ Q U) J is solved by blocks as LAPACK's trsyl. Real throughout for real operands, complex where either is.
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
std::pair< matrix< T >, matrix< T > > expm_frechet (const matrix< T > &a, const matrix< T > &e, frechet_method method=frechet_method::scaling_pade_squaring)
 e^A and the Fréchet derivative L(A, E) of the exponential at a along e, as scipy.linalg.expm_frechet: by default Al-Mohy and Higham's algorithm 6.4 (2009) as SciPy's: the [m/m] Padé approximant (m 3, 5, 7 or 9) where ‖A‖₁ is within its bound, else m = 13 on 2⁻ˢ A and 2⁻ˢ E, s = ⌈log₂(‖A‖₁ / 4.74)⌉, then s squarings L ← R L + L R, R ← R²; or the exponential of [[A, E], [0, A]], whose blocks are e^A and L(A, E).
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
double expm_cond (const matrix< T > &a)
 The relative condition number of the exponential at a in the Frobenius norm, as scipy.linalg.expm_cond: ‖K‖₂ ‖A‖_F / ‖e^A‖_F, K the n² × n² Kronecker form of the Fréchet derivative (its column i n + j the column-major vec of L(A, eᵢ eⱼᵀ)), ‖K‖₂ its largest singular value. An empty matrix's is 0.
 
matrix< std::complex< double > > sqrtm (const matrix< std::complex< double > > &a)
 The principal square root X of a complex square matrix (X² = A, its eigenvalues of nonnegative real part), as scipy.linalg.sqrtm: by the Schur method, A = Z T Zᴴ, the triangular R² = T column by column (Björck and Hammarling), X = Z R Zᴴ. Where A has no square root (a zero eigenvalue in a Jordan block) the entries that would need one are infinite, as SciPy's.
 
matrix< std::complex< double > > complex_sqrtm (const matrix< double > &a)
 The complex principal square root of a real square matrix, as scipy.linalg.sqrtm answers one with a real eigenvalue below 0: from its real Schur form made complex (SciPy's rsf2csf), its real eigenvalues exactly real, so each root of one below 0 is +i √|λ|.
 
matrix< double > sqrtm (const matrix< double > &a)
 The real principal square root of a real square matrix, as scipy.linalg.sqrtm answers one: in real arithmetic on its real Schur form (Higham, 1987), a complex pair's block by its own real root.
 
funm_result funm_from_schur (const matrix< std::complex< double > > &t, const matrix< std::complex< double > > &z, const std::vector< std::complex< double > > &values)
 f(A) from the complex Schur form A = Z T Zᴴ and f at T's diagonal (values), as scipy.linalg.funm completes it: Parlett's recurrence (Golub and Van Loan's algorithm 11.1.1) on F, a superdiagonal at a time, F(i, j) = (T(i, j) (F(j, j) − F(i, i)) + Σ T(i, k) F(k, j) − Σ F(i, k) T(k, j)) / (T(j, j) − T(i, i)) (not divided where two diagonal entries are equal, as SciPy's, the error estimate then 1), then Z F Zᴴ. The estimate: the recurrence run again on its roundings (detail::recurrence_error), or SciPy's where larger, δ the smallest |T(j, j) − T(i, i)| met (or |T(0, 0)|, ε where 0); SciPy's alone said 6·10⁻¹⁴ of an error of 2·10⁻¹¹ (order 16, eigenvalues 0.27 apart, T's strict upper triangle 5 N(0, 1)).
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
funm_plan plan_funm (const matrix< T > &a)
 The funm_plan of a: f is then wanted at its points, and finish_funm completes f(A).
 
funm_result finish_funm (const funm_plan &plan, const std::vector< std::complex< double > > &images)
 f(A) from its funm_plan and images, f at the plan's points: a Hermitian A's V f(Λ) Vᴴ, its estimate ε; where eigenvalues gather, Davies and Higham's Schur–Parlett algorithm with each cluster by Cauchy's integral (detail::clustered_function); else Parlett's recurrence, as SciPy's (funm_from_schur). The estimate ∞ where f at an eigenvalue, or the result, is not finite.
 
std::vector< std::complex< double > > funm_points (const funm_plan &plan)
 The points where finish_funm wants f for plan (not Hermitian) with its circles' counts: its eigenvalues, then each circle's.
 
funm_plan regathered (funm_plan plan, double share)
 plan (not Hermitian) with its eigenvalues gathered anew within share of the largest modulus (or of 1): its Schur form reordered by the finer clusters (the same form, their runs moved), its points the eigenvalues, then detail::contour_points on each circle where clusters remain.
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
funm_result funm (const matrix< T > &a, const std::function< std::vector< std::complex< double > >(const std::vector< std::complex< double > > &)> &f)
 A function of a square matrix, as scipy.linalg.funm: plan_funm, f called once with the plan's points (the eigenvalues, then the circles' where eigenvalues gather) returning one value each, then finish_funm. f must be analytic on each circle's disk. Accurate where the eigenvalues are well apart or gather tightly; between, Parlett's recurrence (the estimate says how).
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< std::complex< double > > fractional_matrix_power (const matrix< T > &a, double p)
 A^p for a real p, as scipy.linalg.fractional_matrix_power: a whole p by repeated squaring; for p > 0, an exactly Hermitian (real symmetric) A by one eigendecomposition, V Λᵖ Vᴴ (Hermitian where no eigenvalue is below 0); else A^a A^b with a the floor or the ceiling of p, chosen by A's condition as SciPy chooses it, and A^b (|b| < 1) by Higham and Lin's Schur–Padé algorithm (2013) on the Schur form. Where the triangular form has a zero on its diagonal (A singular), a positive p falls back to funm of x^(p − ⌊p⌋), as SciPy's; a negative one has no answer and is refused (SciPy returns a matrix of NaN). Complex: a real matrix's power may be complex.
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
logm_result logm (const matrix< T > &a)
 The principal logarithm of a square matrix, as scipy.linalg.logm: an upper triangular A directly, else its Schur form A = Z T Zᴴ and Z log(T) Zᴴ: in real arithmetic where A is real and its real Schur form triangular with no eigenvalue below 0, else in the complex form (the real one made complex), as SciPy's. log T by Al-Mohy and Higham's inverse scaling and squaring (2012) as SciPy's _logm_triu, the norms that choose the square roots and the degree exact where SciPy estimates them. A zero eigenvalue is taken as 10⁻²⁰ (no logarithm exists there), as SciPy's, and reported; complex, SciPy's real part where A is real and it is negligible.
 
void release_memory ()
 Frees the workspaces NumericAL keeps between calls, as oneMKL's mkl_free_buffers: each thread keeps the buffers its kernels last needed (a matrix product's packing, a solve's copies, an eigh's merges, an FFT's scratch), so the next call of a size faults no fresh page in (a solve of order 1000 spent 2.5 ms of its 30 on them), and freed blocks of a few megabytes are kept for the next buffer that fits one. A long-lived process (a server, a notebook) that is done with large problems can give that memory back.
 
void set_max_threads (std::size_t threads) noexcept
 Caps the threads a kernel uses at threads, the caller's included (1: none beside it, and no thread is started); 0 lifts the cap. For a process that runs several kernels side by side (one per worker process, say), so that together they do not ask for more threads than the machine has.
 
std::size_t environment_threads (const char *numerical, const char *omp) noexcept
 The cap of threads the environment asks for, as the Python package and OpenBLAS read it: numerical (NUMERICAL_NUM_THREADS's value) where it is set and not blank, else the first count of omp (OMP_NUM_THREADS's, which joblib and loky set in their workers); null for an unset variable. 0 (no cap) where neither gives a count, or for one that is not a run of digits; above 2³¹, 2³¹.
 
std::size_t max_threads ()
 The threads a kernel may use: the cap if one is set, else the hardware threads (starting none).
 
template<field T>
vector< T > lstsq (const matrix< T > &a, const vector< T > &b, rank_cutoff cutoff={})
 The minimum-norm least-squares solution of A x ≈ b, as NumPy's lstsq gives it.
 
template<field T>
matrix< T > lstsq (const matrix< T > &a, const matrix< T > &b, rank_cutoff cutoff={})
 The minimum-norm least-squares solution of A X ≈ B for every column of B at once, as numpy.linalg.lstsq with a matrix right-hand side: one SVD of A, X = V Σ⁺ Uᴴ B; or, where a bound on the condition number shows the rank full with room to spare, the same solution to rounding by one QR factorisation (detail::lstsq_by_qr).
 
template<field T>
vector< double > singular_values (const matrix< T > &a)
 The singular values of a, descending, without its singular vectors, as numpy.linalg.svd(a, compute_uv=False): the Householder R of a tall A (of Aᴴ when wide), its Golub–Kahan bidiagonal and the dqds algorithm on it (LAPACK's dlasq1, as dgesdd takes it without vectors), no basis formed. Each value to an absolute accuracy of the largest times the machine epsilon, as svd_decomposition's; those of a bidiagonal A each to high relative accuracy.
 
template<field T>
vector< double > symmetric_eigenvalues (const matrix< T > &a)
 The eigenvalues of the real symmetric or complex Hermitian a, ascending, without its eigenvectors, as numpy.linalg.eigvalsh: its Householder tridiagonal (no basis formed) and the implicit QL iteration on it, no rotation kept. Only the lower triangle is read, and of the diagonal its real part. Each value to an absolute accuracy of the largest magnitude times the machine epsilon, as symmetric_eigen's; a graded tridiagonal's small values to their relative accuracy, as LAPACK's dsteqr keeps them.
 
vector< double > tridiagonal_eigenvalues (const vector< double > &d, const vector< double > &e)
 The eigenvalues of the real symmetric tridiagonal matrix of diagonal d and off-diagonal e, ascending, as scipy.linalg.eigvalsh_tridiagonal: the implicit QL iteration, no rotation kept, on the matrix divided by the power of two of its largest magnitude (as symmetric_eigenvalues runs it on the tridiagonal it forms).
 
vector< double > tridiagonal_eigenvalues (const vector< double > &d, const vector< double > &e, std::size_t first, std::size_t last)
 The eigenvalues of indices first to last (ascending, from 0) of the real symmetric tridiagonal matrix of diagonal d and off-diagonal e, as LAPACK's dstebz (scipy.linalg.eigvalsh_tridiagonal with a selection): each by bisection of Gershgorin's interval on Sturm's counts, to ε ‖T‖ (LAPACK's tolerance when none is given), on the matrix divided by the power of two of its largest magnitude. n k operations a bisection step where the QL iteration takes n² for all.
 
std::pair< std::ptrdiff_t, std::ptrdiff_t > tridiagonal_eigenvalue_range (const vector< double > &d, const vector< double > &e, double low, double high)
 The indices [first, last] (ascending, from 0) of the eigenvalues in (low, high] of the real symmetric tridiagonal matrix of diagonal d and off-diagonal e, by Sturm's counts (last < first where none lies there), as dstebz selects them with a range.
 
matrix< double > tridiagonal_eigenvectors (const vector< double > &d, const vector< double > &e, const vector< double > &values)
 The orthonormal eigenvectors (the columns, in their order) of the real symmetric tridiagonal matrix of diagonal d and off-diagonal e for the eigenvalues values, ascending (from tridiagonal_eigenvalues with indices, say), as LAPACK's dstein: inverse iteration (detail::inverse_iteration), some n operations a solve for each, where all the eigenvectors take n³; on the matrix divided by the power of two of its largest magnitude. Where an iterate does not converge or a cluster is too large, the vectors are the whole spectrum's (tridiagonal_eigen) of the eigenvalues nearest.
 
std::pair< vector< double >, matrix< double > > tridiagonal_eigen (const vector< double > &d, const vector< double > &e)
 The eigenvalues, ascending, and the orthonormal eigenvectors (the columns, in their order) of the real symmetric tridiagonal matrix of diagonal d and off-diagonal e, as scipy.linalg.eigh_tridiagonal: divide and conquer (LAPACK's dstedc, the eigenvectors by matrix products), the implicit QL iteration up to its leaves' order, on the matrix divided by the power of two of its largest magnitude.
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
eigen_subset< T > hermitian_eigen_subset (const matrix< T > &a, std::size_t first, std::size_t last, bool vectors=true)
 The eigenvalues of indices first to last (ascending, from 0) of the real symmetric or complex Hermitian a, its lower triangle read, and their eigenvectors where vectors, as scipy.linalg.eigh(a, subset_by_index=[first, last]): the tridiagonal form (LAPACK's sytrd, hetrd), the eigenvalues by bisection (tridiagonal_eigenvalues, stebz), the vectors by inverse iteration (detail::inverse_iteration, stein) taken back through the reflections (ormtr, unmtr): past the reduction, n² k operations where the whole spectrum's vectors take n³ and more. On the matrix divided by the power of two of its largest magnitude. Where an iterate does not converge or a cluster of eigenvalues is too large, the vectors are the whole spectrum's by divide and conquer.
 
template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
eigen_subset< T > hermitian_eigen_subset_by_value (const matrix< T > &a, double low, double high, bool vectors=true)
 hermitian_eigen_subset of the eigenvalues in (low, high], as scipy.linalg.eigh(a, subset_by_value=[low, high]): their indices by Sturm's counts on the tridiagonal form (tridiagonal_eigenvalue_range); none, the vectors n × 0.
 
template<typename T >
least_squares_solution< T > least_squares (const matrix< T > &a, const matrix< T > &b, rank_cutoff cutoff={})
 lstsq, with the residuals, the rank and the singular values numpy.linalg.lstsq returns beside the solution: the residual sums of squares are given only where the solution is unique and need not be exact, A tall (m > n) and of full column rank, as NumPy gives them.
 
template<field T>
std::size_t matrix_rank (const matrix< T > &a, rank_cutoff cutoff={}, bool hermitian=false)
 The numerical rank of a, as numpy.linalg.matrix_rank counts it: its singular values above cutoff.
 
template<field T>
matrix< T > pinv (const matrix< T > &a, rank_cutoff cutoff={}, bool hermitian=false)
 The Moore–Penrose pseudo-inverse of the m × n a (n × m), as numpy.linalg.pinv gives it: V Σ⁺ Uᴴ, a singular value at or under cutoff counting as zero.
 
template<typename T >
bool approx_equal (const tensor< T > &a, const tensor< T > &b, double tolerance=1e-9)
 Element-wise closeness within a tolerance (for inexact scalars).
 
std::vector< std::size_t > broadcast_shape (const std::vector< std::size_t > &a, const std::vector< std::size_t > &b)
 The shape two shapes broadcast to, as NumPy's broadcast_shapes.
 
template<typename T , typename ... Rest>
tensor< T > einsum (const std::string &spec, const tensor< T > &first, const Rest &... rest)
 Einstein summation over one or more tensor operands.
 
template<typename T >
tensor< T > einsum (const std::string &spec, const std::vector< const tensor< T > * > &operands)
 Einstein summation over operands counted at run time: einsum for a caller that holds them in a container (an interpreter evaluating einsum("ij,jk->ik", a, b) from a parse).
 
template<typename T >
tensor< T > matmul (const tensor< T > &a, const tensor< T > &b)
 The matrix product of two tensors, as NumPy's matmul: each operand a stack of matrices along its leading axes, those axes broadcast against the other's (aligned from the right, an extent of 1 repeated), one product per matrix of the broadcast stack through the packed kernel, the products in parallel. A vector first is a row (its axis absent from the result), a vector second a column (likewise); two vectors give their dot product, of rank 0. The broadcast operands are not copied: a repeated matrix is read where it is.
 
template<typename T , typename Op >
auto broadcast_apply (const tensor< T > &a, const tensor< T > &b, const Op &op)
 op(a, b) element by element, the operands broadcast against each other, in op's result type (a comparison's bools): a view read where it lies close (a slice), copied otherwise. One element against a tensor of as many axes or more is a number, the other read as detail::parallel_map reads it (a transpose's elements as they lie); two transposes alike, their elements paired as they lie.
 
template<typename T >
tensor< T > exp (const tensor< T > &a)
 exp of every element: detail::exp_into of a double one (within 0.506 ulp of the exact value), std::exp of a float one, detail::complex_exp of a complex one.
 
template<std::floating_point T>
tensor< T > expm1 (const tensor< T > &a)
 exp(x) − 1 of every real element, exact near 0: detail::expm1_into of a double one (within 0.503 ulp of the exact value), the double's rounded once of a float one (detail::through_doubles, within half an ulp and 2⁻²⁸).
 
template<std::floating_point T>
tensor< T > atan (const tensor< T > &a)
 atan of every real element: detail::atan_into of a double one (within 0.501 ulp of the exact value), the double's rounded once of a float one (detail::through_doubles, within half an ulp and 2⁻²⁸).
 
template<std::floating_point T>
tensor< T > sinh (const tensor< T > &a)
 sinh of every real element: detail::sinh_into of a double one (within 0.503 ulp of the exact value, finite up to the overflow past 710.47), the double's rounded once of a float one (detail::through_doubles, within half an ulp and 2⁻²⁸).
 
template<std::floating_point T>
tensor< T > cosh (const tensor< T > &a)
 cosh of every real element: detail::cosh_into of a double one (within 0.501 ulp of the exact value, finite up to the overflow past 710.47), the double's rounded once of a float one (detail::through_doubles, within half an ulp and 2⁻²⁸).
 
template<std::floating_point T>
tensor< T > exp2 (const tensor< T > &a)
 2^x of every real element: detail::exp2_into of a double one (within 0.506 ulp of the exact value where it is normal, exact at every integer), std::exp2 of a float one.
 
template<typename T >
tensor< T > log (const tensor< T > &a)
 log of every element: std::log of a real one, detail::complex_log of a complex one.
 
template<std::floating_point T>
tensor< T > log1p (const tensor< T > &a)
 log(1 + x) of every real element, exact near 0: detail::log1p_into of a double one (within 0.501 ulp of the exact value), the double's rounded once of a float one (detail::through_doubles, within half an ulp and 2⁻²⁸).
 
template<typename T >
tensor< T > sin (const tensor< T > &a)
 sin of every element: std::sin of a real one (a float the double's, detail::sin_of), detail::complex_sin of a complex one.
 
template<typename T >
tensor< T > cos (const tensor< T > &a)
 cos of every element: std::cos of a real one (a float the double's, detail::cos_of), detail::complex_cos of a complex one.
 
template<typename T >
tensor< T > tan (const tensor< T > &a)
 tan of every element: std::tan of a real one, detail::complex_tan of a complex one.
 
template<typename T >
tensor< T > tanh (const tensor< T > &a)
 tanh of every element: detail::tanh_into of a double one (within 0.502 ulp of the exact value), the double's rounded once of a float one (detail::through_doubles, within half an ulp and 2⁻²⁸), detail::complex_tanh of a complex one.
 
template<typename T >
tensor< T > sqrt (const tensor< T > &a)
 The square root of every element: std::sqrt of a real one, detail::complex_sqrt of a complex one.
 
template<typename T >
tensor< T > operator+ (const tensor< T > &a, const tensor< T > &b)
 Element-wise sum, broadcast (a signed integer's wrapped, detail::arithmetic).
 
template<std::floating_point T>
tensor< T > maximum (const tensor< T > &a, const tensor< T > &b)
 The larger element of a and b, broadcast, as numpy.maximum (detail::ieee_maximum; a NaN wins, +0 over −0).
 
template<std::floating_point T>
tensor< T > minimum (const tensor< T > &a, const tensor< T > &b)
 The smaller element of a and b, broadcast, as numpy.minimum (detail::ieee_minimum; a NaN wins, −0 under +0).
 
template<std::floating_point T>
tensor< T > round (const tensor< T > &a, int decimals=0)
 Every element rounded to decimals places (tens, hundreds for a negative one), half to even, as numpy.round; a value already exact to those places is kept (detail::decimal_rounding).
 
template<detail::split_complex C>
tensor< C > round (const tensor< C > &a, int decimals=0)
 Every element's real and imaginary parts rounded to decimals places apart, as numpy.round of a complex array.
 
template<std::floating_point T>
tensor< T > clip (const tensor< T > &a, T low, T high)
 a limited to [low, high] element by element, as numpy.clip of two numbers: minimum(maximum(a, low), high) in one pass, the same bits as the two (detail::ieee_maximum, then detail::ieee_minimum; a NaN wins, a NaN bound's too), by detail::clipped where no bound is a NaN.
 
template<typename T >
tensor< T > operator- (const tensor< T > &a, const tensor< T > &b)
 Element-wise difference, broadcast.
 
template<typename T >
tensor< T > operator* (const tensor< T > &a, const tensor< T > &b)
 Element-wise product, broadcast.
 
template<typename T >
tensor< T > operator/ (const tensor< T > &a, const tensor< T > &b)
 Element-wise quotient, broadcast.
 
template<typename T >
tensor< T > floor_divide (const tensor< T > &a, const tensor< T > &b)
 a // b element by element, broadcast, as numpy.floor_divide (detail::floor_divmod).
 
template<typename T >
tensor< T > remainder (const tensor< T > &a, const tensor< T > &b)
 a % b element by element, broadcast, as numpy.remainder (Python's: of b's sign; a real by zero fmod's NaN, detail::floor_divmod).
 
template<typename T >
tensor< T > operator- (const tensor< T > &a)
 Element-wise negation.
 
template<typename T , typename F >
auto map (const tensor< T > &t, const F &f) -> tensor< std::decay_t< decltype(f(std::declval< const T & >()))> >
 f(x) for every element, in a tensor of the same shape and of f's result type.
 
template<typename T >
tensor< T > pow (const tensor< T > &a, const tensor< T > &b)
 a to the power b element by element, broadcast, as std::pow; a single exponent of 2, 0.5 or -1 as the library's own x * x, square root (detail::complex_sqrt for a complex one) and 1 / x (exact where pow rounds: a complex square has no stray real part). A complex one keeps C's Annex G, as the operators do: NumPy's loops are detail::numpy_square, detail::numpy_reciprocal and detail::numpy_power.
 
template<typename T >
T sum (const tensor< T > &t)
 The sum of every element, by pairwise halving (0 for an empty tensor), on the threads where they are many (detail::parallel_pairwise_sum): the same bits.
 
template<typename T >
tensor< T > sum (const tensor< T > &t, std::size_t axis)
 The sums along axis, by pairwise halving; a transpose's where its elements lie (detail::as_laid_reduced; each line's sum the same).
 
template<typename T >
T mean (const tensor< T > &t)
 The mean of every element. An empty tensor's mean is NaN, as NumPy's (which also warns).
 
template<typename T >
tensor< T > mean (const tensor< T > &t, std::size_t axis)
 The means along axis; a transpose's where its elements lie (detail::as_laid_reduced).
 
template<std::totally_ordered T>
T max (const tensor< T > &t)
 The largest element (a NaN, if there is one), of a transpose's elements as they lie (in any order the same).
 
template<std::totally_ordered T>
T min (const tensor< T > &t)
 The smallest element (a NaN, if there is one), of a transpose's elements as they lie (in any order the same).
 
template<typename T >
T prod (const tensor< T > &t)
 The product of every element, in order (numpy.prod's, whose multiplications are sequential: only its sums pair). An empty tensor's is 1.
 
template<typename T >
tensor< T > prod (const tensor< T > &t, std::size_t axis)
 The products along axis, each line in order; a transpose's where its elements lie (detail::as_laid_reduced).
 
template<typename T >
tensor< T > cumsum (const tensor< T > &t, std::size_t axis)
 The running sums along axis, in order, as numpy.cumsum.
 
template<typename T >
tensor< T > cumprod (const tensor< T > &t, std::size_t axis)
 The running products along axis, in order, as numpy.cumprod.
 
template<typename T >
tensor< T > sort (const tensor< T > &t, std::size_t axis)
 The elements sorted along axis, as numpy.sort: ascending, NaNs last, equal elements in their order (NumPy's kind="stable"; its default sort may order equal ones otherwise, which only a sign of zero shows).
 
template<typename T >
tensor< std::int64_t > argsort (const tensor< T > &t, std::size_t axis)
 The indices that sort the elements along axis, as numpy.argsort (its kind="stable"): of each line, in the order sort puts its elements, equal ones by index. A long line is sorted among the threads (detail::parallel_sort_run).
 
template<typename T >
tensor< T > partition (const tensor< T > &t, const std::vector< std::size_t > &kths, std::size_t axis)
 The elements of each line along axis rearranged as numpy.partition: at each of kths the element sort puts there (NaNs last, a complex number by its real part then its imaginary part), none before it that sorts after it, none after it that sorts before; the others in no order specified. By selection, std::nth_element between neighbouring positions, linear in the extent where sort is not.
 
template<typename T >
tensor< std::int64_t > argpartition (const tensor< T > &t, const std::vector< std::size_t > &kths, std::size_t axis)
 The indices that partition each line along axis, as numpy.argpartition: of the elements partition would put at each of kths and around it, by selection; equal elements in no order specified.
 
template<typename T >
T vdot (const tensor< T > &a, const tensor< T > &b)
 Σ conj(a[i]) · b[i] over every element of a and b in their row-major order, as numpy.vdot: the plain sum of products for reals, the conjugated one for complex numbers without a conjugated copy of a (detail::chunked_conjugate_dot, BLAS's zdotc), both by chunks among the threads, the same on any number of them.
 
template<typename T >
tensor< std::int64_t > argsort_by (const tensor< std::int64_t > &order, const tensor< T > &key, std::size_t axis)
 order, indices along axis into key of its shape, each line's sorted stably by the elements of key they index, as numpy.argsort sorts (NaNs last): equal elements keep their places in order. A sort by the keys of numpy.lexsort in turn, from its least significant, each reading the key where it lies (no gather of the key into the order before its sort). The lines on the threads, or one long line among them.
 
template<typename T >
std::int64_t argmax (const tensor< T > &t)
 The flat index of the first largest element, as numpy.argmax (the first NaN where there is one).
 
template<typename T >
std::int64_t argmin (const tensor< T > &t)
 The flat index of the first smallest element, as numpy.argmin (the first NaN where there is one).
 
template<typename T >
tensor< std::int64_t > argmax (const tensor< T > &t, std::size_t axis)
 The index of the first largest element of every line along axis, as numpy.argmax.
 
template<typename T >
tensor< std::int64_t > argmin (const tensor< T > &t, std::size_t axis)
 The index of the first smallest element of every line along axis, as numpy.argmin.
 
template<typename T >
std::vector< tensor< std::int64_t > > nonzero (const tensor< T > &t)
 The indices of the nonzero elements (x != T {}: a NaN is one), one tensor per axis, in C order, as numpy.nonzero: by chunks on the threads, each chunk's counted, then its indices written at its offset. A chunk walks its elements' indices as an odometer (one division per axis at its start, none after) and writes every element's, the place advancing by one where it is nonzero, without a branch; into a buffer of its own, whose last write may run one past its part.
 
template<typename T >
std::size_t count_nonzero (const tensor< T > &t)
 The number of nonzero elements (x != T {}: a NaN is one), as numpy.count_nonzero without an axis: by chunks on the threads, each chunk's counted without a branch, then the counts summed; a transpose's as its elements lie (tensor::laid_out), none copied.
 
template<typename T >
tensor< std::int64_t > count_nonzero (const tensor< T > &t, std::size_t axis)
 The number of nonzero elements (x != T {}) along axis, as numpy.count_nonzero.
 
template<typename T >
tensor< T > take_along_axis (const tensor< T > &t, const tensor< std::int64_t > &indices, std::size_t axis)
 The elements of t at indices along axis, the other axes matched, as numpy.take_along_axis: indices of t's rank and shape but along the axis (any extent there), each in [0, extent); read directly, on the threads.
 
template<typename T >
tensor< T > take (const tensor< T > &t, const tensor< std::int64_t > &indices, std::size_t axis, take_mode mode)
 The elements of t at indices along axis, as numpy.take: the result's shape t's with the axis replaced by indices' shape. Under take_mode::raise a negative index counts from the axis's end; under wrap an index is taken modulo the extent; under clip, at the nearer end. Each index read once, then the elements copied on the threads.
 
template<typename T >
tensor< T > select_along_last (const tensor< T > &t, const tensor< std::int64_t > &positions)
 Of each line along the last axis of t, the elements its stable sort (sort) puts at the positions positions names, as sort(t)[..., positions] reads them, without the sort: each line's positions found by selection (detail::select_row), the lines on the threads. positions has shape (m,), the same for every line, or the lines' shape and m; the result, the lines' shape and m.
 
template<typename T >
tensor< T > correlate (const tensor< T > &a, const tensor< T > &v, std::ptrdiff_t first, std::size_t count)
 The cross-correlation c[k] = Σₙ a[n + k] · conj(v[n]) of two vectors over the lags first … first + count − 1 (from −(len v − 1), the full range's first, to len a − 1), as numpy.correlate's: each lag's sum in the order of v's terms, a complex product NumPy's rounded one (no infinity recovered), an integer's wrapped; the lags on the threads, by blocks (detail::correlation_block lags), those of a block where v lies within a summed together, a term of each per term of v (in vectors, each lag's sum still its own), the others one by one.
 
template<typename T >
tensor< std::int64_t > searchsorted (const tensor< T > &a, const tensor< T > &v, bool right=false)
 Where each element of v would go in the sorted line a to keep it sorted, as numpy.searchsorted: the first such place (right false) or the last, in detail::sorts_before's order (NaNs last).
 
template<std::totally_ordered T>
tensor< T > max (const tensor< T > &t, std::size_t axis)
 The largest elements along axis; a transpose's where its elements lie (detail::as_laid_reduced).
 
template<std::totally_ordered T>
tensor< T > min (const tensor< T > &t, std::size_t axis)
 The smallest elements along axis; a transpose's where its elements lie (detail::as_laid_reduced).
 
template<typename T >
tensor< T > broadcast_to (const tensor< T > &t, std::vector< std::size_t > shape)
 t repeated along its axes of extent 1 and new leading ones to shape, as numpy.broadcast_to (a copy: a tensor's elements are contiguous): each row of the result copied from its row of t, or filled with its one element where the last axis broadcasts, the rows on the threads.
 
template<typename T >
tensor< T > reshape (const tensor< T > &t, std::vector< std::size_t > shape)
 The same elements in the same order under another shape, shared with t (no copy).
 
template<typename T >
tensor< T > diagonal (const tensor< T > &t, std::ptrdiff_t offset)
 The offset diagonal of each matrix of t (its last two axes), as numpy.linalg.diagonal: above the main diagonal for a positive offset, below for a negative one: a view (tensor::diagonal_view), no element copied but a few; the batch's shape, then the diagonal's length (0 where offset passes the matrix).
 
template<typename T >
tensor< T > triangle (const tensor< T > &t, std::ptrdiff_t k, bool lower)
 The matrices of t (its last two axes) zero above their k diagonal (lower) or below it (else), as numpy.tril and numpy.triu: each row's kept part copied and the rest zeroed, by rows on the threads.
 
std::array< tensor< std::int64_t >, 2 > triangle_indices (std::size_t rows, std::size_t cols, std::ptrdiff_t k, bool lower)
 The row and the column indices of the rows × cols matrix's part to and below its k diagonal (lower) or to and above it (else), in row-major order, as numpy.tril_indices and numpy.triu_indices: each row's count, their offsets, then the rows written on the threads.
 
template<typename T >
tensor< T > full (std::vector< std::size_t > shape, const T &value)
 A tensor of shape with every element value.
 
template<typename T >
tensor< T > zeros (std::vector< std::size_t > shape)
 A tensor of shape full of zeros (each thread's share zeroed as the C library zeroes).
 
template<typename T >
tensor< T > diag (const tensor< T > &v, std::ptrdiff_t k)
 The square matrix with the vector v on its k diagonal (above the main one for a positive k) and zeros elsewhere, as numpy.diag of a vector: of order len v + |k|.
 
template<typename T >
tensor< T > ones (std::vector< std::size_t > shape)
 A tensor of shape full of ones.
 
template<typename T >
tensor< T > eye (std::size_t n)
 The n × n identity.
 
tensor< double > arange (double start, double stop, double step, bool fused=true)
 start, start + step, … below stop (above it for a negative step), as NumPy's arange: its length is ceil((stop − start) / step), its first two elements start itself (a zero's sign kept) and start + step, and element i after them start + i·delta with delta = (start + step) − start, the step as the first two elements hold it: rounded once where fused (a fused multiply-add, as NumPy's macOS arm64 wheels compute it), else the product rounded first (NumPy's other wheels), which can differ in the last bits.
 
tensor< double > linspace (double start, double stop, std::size_t count)
 count values evenly spaced from start to stop, both included, as NumPy's linspace: element i is start + i·step with step = (stop − start) / (count − 1), and the last is stop exactly.
 
template<typename T >
vector< T > operator+ (const vector< T > &a, const vector< T > &b)
 Element-wise sum.
 
template<typename T >
vector< T > operator- (const vector< T > &a, const vector< T > &b)
 Element-wise difference.
 
template<typename T >
vector< T > operator* (const T &scalar, const vector< T > &v)
 Scalar times vector.
 
template<typename T >
vector< T > operator* (const vector< T > &v, const T &scalar)
 Vector times scalar.
 
template<typename T >
T dot (const vector< T > &a, const vector< T > &b)
 Dot product.
 
template<typename T >
bool approx_equal (const vector< T > &a, const vector< T > &b, double tolerance=1e-9)
 Element-wise closeness within a tolerance (for inexact scalars).
 

Variables

constexpr std::size_t transpose_tile {32}
 The square blocks transpose copies one at a time: a block's rows of the source and of the result both stay in the L1 cache, where a row of the result walked a column of the source a stride apart.
 
constexpr std::size_t hermitian_expm_least {64}
 The order from which expm of a Hermitian matrix takes its eigendecomposition (below, the Padé path is faster: an order-32 symmetric_eigen costs more than the few products of a small Padé degree).
 
constexpr std::size_t sliced_copy_most {512}
 The most elements tensor::sliced copies at once rather than viewing (4 KiB of doubles).
 

Detailed Description

The NumericAL public API.

Typedef Documentation

◆ buffer

The storage of vector, matrix and tensor, namely a std::vector whose buffer<T>(n) and resize(n) leave a double or a complex number uninitialised, for a result about to be written in full. buffer<T>(n, T {}) zeroes, as std::vector<T>(n) does.

Definition at line 443 of file buffer.hpp.

Enumeration Type Documentation

◆ eigen_method

How numerical::symmetric_eigen diagonalises.

Enumerator
tridiagonal_ql 

Householder tridiagonalisation then implicit QL, as LAPACK's dsyev: the vectors by rotations.

jacobi 

Cyclic Jacobi rotations: several times slower, kept as an independent second method.

divide_and_conquer 

Householder tridiagonalisation then divide and conquer, as LAPACK's dsyevd: the default.

Definition at line 6655 of file factorizations.hpp.

◆ fft_norm

How a transform and its inverse are scaled, as NumPy's norm.

Enumerator
backward 

The forward transform unscaled, the inverse scaled by 1/n (NumPy's default).

ortho 

Both scaled by 1/√n: a unitary pair.

forward 

The forward transform scaled by 1/n, the inverse unscaled.

Definition at line 52 of file fft.hpp.

◆ frechet_method

How expm_frechet computes: Al-Mohy and Higham's algorithm (SciPy's "SPS"), or the exponential of the block matrix [[A, E], [0, A]] ("blockEnlarge").

Enumerator
scaling_pade_squaring 

Al-Mohy and Higham's algorithm 6.4.

block_enlarge 

expm of the 2n × 2n block matrix.

Definition at line 1087 of file matrix_functions.hpp.

◆ gemm_path

enum class numerical::gemm_path : std::uint8_t
strong

The kernels a double matrix product can run on (a float one too on arm64), from the most portable. Each is used only where the processor has it: NEON on every arm64 chip, the AVX ones where cpuid reports them, the Apple AMX on an M1 to M4 chip whose self-test passes (see x86.hpp and amx.hpp).

Enumerator
portable 

The compiler's vectors (16 bytes on x86-64 wheels), as the compiler rounds c + a·b (see gemm).

neon 

arm64's vectors with fused multiply-adds, for double and float.

avx2 

AVX2 with fused multiply-adds.

avx512 

AVX-512 with fused multiply-adds.

amx 

The Apple AMX coprocessor, fused multiply-adds; the products it does not suit on the NEON path's tile.

Definition at line 82 of file gemm.hpp.

◆ qr_mode

The factors a numerical::qr_decomposition keeps, as numpy.linalg.qr's modes name them.

Enumerator
reduced 

Q is m × k, R k × n, k = min(m, n): NumPy's default.

complete 

Q is m × m, its columns past k a basis of the complement of A's column space; R is m × n.

Definition at line 3779 of file factorizations.hpp.

◆ svd_method

How numerical::svd_decomposition computes the decomposition of R, after a Householder QR.

Enumerator
bidiagonal_qr 

Golub–Kahan bidiagonalisation then implicit-shift QR, as LAPACK's dgesvd.

jacobi 

One-sided Jacobi: several times slower, each singular value to high relative accuracy.

divide_and_conquer 

Golub–Kahan bidiagonalisation then divide and conquer, as LAPACK's dgesdd: the default.

Definition at line 1550 of file svd.hpp.

◆ take_mode

What take does with an index outside its axis, as numpy.take's mode: refuse it, take it modulo the extent, or take the nearer end.

Enumerator
raise 
wrap 
clip 

Definition at line 4575 of file tensor_ops.hpp.

◆ triangular_op

How solve_triangular reads its matrix: as it lies, transposed, or conjugate-transposed (SciPy's trans 0, 1 and 2).

Enumerator
none 

A X = B.

transpose 

Aᵀ X = B.

adjoint 

Aᴴ X = B.

Definition at line 1833 of file factorizations.hpp.

Function Documentation

◆ approx_equal() [1/3]

template<typename T >
bool numerical::approx_equal ( const matrix< T > &  a,
const matrix< T > &  b,
double  tolerance = 1e-9 
)

Element-wise closeness within a tolerance (for inexact scalars).

Parameters
[in]a,bMatrices to compare.
[in]toleranceMaximum allowed magnitude of each element-wise difference.
Returns
true if the shapes match and every element pair is equal or differs by at most tolerance; a NaN is close to nothing.

Definition at line 276 of file matrix.hpp.

◆ approx_equal() [2/3]

template<typename T >
bool numerical::approx_equal ( const tensor< T > &  a,
const tensor< T > &  b,
double  tolerance = 1e-9 
)

Element-wise closeness within a tolerance (for inexact scalars).

Parameters
[in]a,bTensors to compare.
[in]toleranceMaximum allowed magnitude of each element-wise difference.
Returns
true if the shapes match and every element pair is equal or differs by at most tolerance; a NaN is close to nothing.

Definition at line 630 of file tensor.hpp.

◆ approx_equal() [3/3]

template<typename T >
bool numerical::approx_equal ( const vector< T > &  a,
const vector< T > &  b,
double  tolerance = 1e-9 
)

Element-wise closeness within a tolerance (for inexact scalars).

Parameters
[in]a,bVectors to compare.
[in]toleranceMaximum allowed magnitude of each element-wise difference.
Returns
true if the sizes match and every element pair is equal or differs by at most tolerance; a NaN is close to nothing.

Definition at line 294 of file vector.hpp.

◆ arange()

tensor< double > numerical::arange ( double  start,
double  stop,
double  step,
bool  fused = true 
)
inline

start, start + step, … below stop (above it for a negative step), as NumPy's arange: its length is ceil((stop − start) / step), its first two elements start itself (a zero's sign kept) and start + step, and element i after them start + i·delta with delta = (start + step) − start, the step as the first two elements hold it: rounded once where fused (a fused multiply-add, as NumPy's macOS arm64 wheels compute it), else the product rounded first (NumPy's other wheels), which can differ in the last bits.

Exceptions
dimension_errorIf step is zero or not finite.

Definition at line 5197 of file tensor_ops.hpp.

◆ argmax() [1/2]

template<typename T >
std::int64_t numerical::argmax ( const tensor< T > &  t)

The flat index of the first largest element, as numpy.argmax (the first NaN where there is one).

Exceptions
dimension_errorIf t is empty.

Definition at line 4391 of file tensor_ops.hpp.

◆ argmax() [2/2]

template<typename T >
tensor< std::int64_t > numerical::argmax ( const tensor< T > &  t,
std::size_t  axis 
)

The index of the first largest element of every line along axis, as numpy.argmax.

Exceptions
dimension_errorIf axis is not an axis, or is empty.

Definition at line 4413 of file tensor_ops.hpp.

◆ argmin() [1/2]

template<typename T >
std::int64_t numerical::argmin ( const tensor< T > &  t)

The flat index of the first smallest element, as numpy.argmin (the first NaN where there is one).

Exceptions
dimension_errorIf t is empty.

Definition at line 4402 of file tensor_ops.hpp.

◆ argmin() [2/2]

template<typename T >
tensor< std::int64_t > numerical::argmin ( const tensor< T > &  t,
std::size_t  axis 
)

The index of the first smallest element of every line along axis, as numpy.argmin.

Exceptions
dimension_errorIf axis is not an axis, or is empty.

Definition at line 4425 of file tensor_ops.hpp.

◆ argpartition()

template<typename T >
tensor< std::int64_t > numerical::argpartition ( const tensor< T > &  t,
const std::vector< std::size_t > &  kths,
std::size_t  axis 
)

The indices that partition each line along axis, as numpy.argpartition: of the elements partition would put at each of kths and around it, by selection; equal elements in no order specified.

Exceptions
dimension_errorIf axis is not an axis.
index_errorIf a position is past the extent.

Definition at line 4102 of file tensor_ops.hpp.

◆ argsort()

template<typename T >
tensor< std::int64_t > numerical::argsort ( const tensor< T > &  t,
std::size_t  axis 
)

The indices that sort the elements along axis, as numpy.argsort (its kind="stable"): of each line, in the order sort puts its elements, equal ones by index. A long line is sorted among the threads (detail::parallel_sort_run).

Exceptions
dimension_errorIf axis is not an axis.

Definition at line 3987 of file tensor_ops.hpp.

◆ argsort_by()

template<typename T >
tensor< std::int64_t > numerical::argsort_by ( const tensor< std::int64_t > &  order,
const tensor< T > &  key,
std::size_t  axis 
)

order, indices along axis into key of its shape, each line's sorted stably by the elements of key they index, as numpy.argsort sorts (NaNs last): equal elements keep their places in order. A sort by the keys of numpy.lexsort in turn, from its least significant, each reading the key where it lies (no gather of the key into the order before its sort). The lines on the threads, or one long line among them.

Exceptions
dimension_errorIf the shapes differ, axis is not an axis, or an index is out of the axis's range.

Definition at line 4174 of file tensor_ops.hpp.

◆ atan()

template<std::floating_point T>
tensor< T > numerical::atan ( const tensor< T > &  a)

atan of every real element: detail::atan_into of a double one (within 0.501 ulp of the exact value), the double's rounded once of a float one (detail::through_doubles, within half an ulp and 2⁻²⁸).

Definition at line 2674 of file tensor_ops.hpp.

◆ band_tridiagonal()

template<typename T >
band_tridiagonal_form< T > numerical::band_tridiagonal ( const matrix< T > &  lower,
bool  basis 
)

Reduces the real symmetric or complex Hermitian band matrix whose lower form is lower ((u + 1) × n, entry (d, j) the matrix's (j + d, j)) to a real symmetric tridiagonal one, as LAPACK's dsbtrd and zhbtrd: each column's entries below the first subdiagonal annihilated by plane rotations, from the farthest in, each rotation's bulge chased down the band by u rows at a time, in n² u operations; then the off-diagonal made real and non-negative by a diagonal of phases. With basis, the rotations' product (and the phases), W, so that the eigenvectors of A are W times those of T.

Exceptions
dimension_errorIf lower has no row.

Definition at line 3801 of file eigen.hpp.

◆ block_diag()

template<typename T >
matrix< T > numerical::block_diag ( const std::vector< matrix< T > > &  blocks)

The block diagonal matrix of blocks, in order, as scipy.linalg.block_diag: zeros off the blocks.

Definition at line 893 of file banded.hpp.

◆ broadcast_apply()

template<typename T , typename Op >
auto numerical::broadcast_apply ( const tensor< T > &  a,
const tensor< T > &  b,
const Op &  op 
)

op(a, b) element by element, the operands broadcast against each other, in op's result type (a comparison's bools): a view read where it lies close (a slice), copied otherwise. One element against a tensor of as many axes or more is a number, the other read as detail::parallel_map reads it (a transpose's elements as they lie); two transposes alike, their elements paired as they lie.

Exceptions
dimension_errorIf the shapes do not broadcast.

Definition at line 2153 of file tensor_ops.hpp.

◆ broadcast_shape()

std::vector< std::size_t > numerical::broadcast_shape ( const std::vector< std::size_t > &  a,
const std::vector< std::size_t > &  b 
)
inline

The shape two shapes broadcast to, as NumPy's broadcast_shapes.

Exceptions
dimension_errorIf an axis has two extents, neither of them 1.

Definition at line 677 of file tensor.hpp.

◆ broadcast_to()

template<typename T >
tensor< T > numerical::broadcast_to ( const tensor< T > &  t,
std::vector< std::size_t >  shape 
)

t repeated along its axes of extent 1 and new leading ones to shape, as numpy.broadcast_to (a copy: a tensor's elements are contiguous): each row of the result copied from its row of t, or filled with its one element where the last axis broadcasts, the rows on the threads.

Exceptions
dimension_errorIf t's shape does not broadcast to shape.

Definition at line 4943 of file tensor_ops.hpp.

◆ cho_solve_banded()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > numerical::cho_solve_banded ( const matrix< T > &  cb,
const matrix< T > &  b,
bool  lower_form = false 
)

The solution X of A X = B from cholesky_banded's factor cb of A, as scipy.linalg.cho_solve_banded((cb, lower_form), b) (LAPACK's pbtrs).

Exceptions
dimension_errorIf cb has no row, or b has not as many rows as cb has columns.
non_finite_errorIf an entry is infinite or NaN.

Definition at line 636 of file banded.hpp.

◆ cholesky()

template<field T>
cholesky_decomposition< T > numerical::cholesky ( matrix< T >  a)

Cholesky-factorises a Hermitian positive-definite matrix.

See also
cholesky_decomposition

Definition at line 2990 of file factorizations.hpp.

◆ cholesky_banded()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > numerical::cholesky_banded ( const matrix< T > &  ab,
bool  lower_form = false 
)

The Cholesky factor of the Hermitian positive-definite band ab, as scipy.linalg.cholesky_banded (LAPACK's pbtrf): in ab's own form, U (A = Uᴴ U) in the upper one, L = Uᴴ (A = L Lᴴ) with lower_form, the corners outside the band as ab has them.

Exceptions
dimension_errorIf ab has no row.
non_finite_errorIf an entry is infinite or NaN.
not_positive_definite_errorIf A is not positive definite.

Definition at line 603 of file banded.hpp.

◆ circulant()

template<typename T >
matrix< T > numerical::circulant ( const vector< T > &  c)

The n × n circulant matrix of first column c, as scipy.linalg.circulant: C(i, j) = c[(i − j) mod n].

Definition at line 860 of file banded.hpp.

◆ clip()

template<std::floating_point T>
tensor< T > numerical::clip ( const tensor< T > &  a,
T  low,
T  high 
)

a limited to [low, high] element by element, as numpy.clip of two numbers: minimum(maximum(a, low), high) in one pass, the same bits as the two (detail::ieee_maximum, then detail::ieee_minimum; a NaN wins, a NaN bound's too), by detail::clipped where no bound is a NaN.

a limited to [low, high] element by element, as numpy.clip of two integers: minimum(maximum(a, low), high) in one pass (high where low passes it, as NumPy's).

Definition at line 2995 of file tensor_ops.hpp.

◆ complex_sqrtm()

matrix< std::complex< double > > numerical::complex_sqrtm ( const matrix< double > &  a)
inline

The complex principal square root of a real square matrix, as scipy.linalg.sqrtm answers one with a real eigenvalue below 0: from its real Schur form made complex (SciPy's rsf2csf), its real eigenvalues exactly real, so each root of one below 0 is +i √|λ|.

Exceptions
dimension_errorIf a is not square.
non_finite_errorIf an entry is infinite or NaN.
convergence_errorIf the Schur form's iterations did not converge.

Definition at line 1531 of file matrix_functions.hpp.

◆ correlate()

template<typename T >
tensor< T > numerical::correlate ( const tensor< T > &  a,
const tensor< T > &  v,
std::ptrdiff_t  first,
std::size_t  count 
)

The cross-correlation c[k] = Σₙ a[n + k] · conj(v[n]) of two vectors over the lags first … first + count − 1 (from −(len v − 1), the full range's first, to len a − 1), as numpy.correlate's: each lag's sum in the order of v's terms, a complex product NumPy's rounded one (no infinity recovered), an integer's wrapped; the lags on the threads, by blocks (detail::correlation_block lags), those of a block where v lies within a summed together, a term of each per term of v (in vectors, each lag's sum still its own), the others one by one.

Definition at line 4854 of file tensor_ops.hpp.

◆ cos()

template<typename T >
tensor< T > numerical::cos ( const tensor< T > &  a)

cos of every element: std::cos of a real one (a float the double's, detail::cos_of), detail::complex_cos of a complex one.

Definition at line 2737 of file tensor_ops.hpp.

◆ cosh()

template<std::floating_point T>
tensor< T > numerical::cosh ( const tensor< T > &  a)

cosh of every real element: detail::cosh_into of a double one (within 0.501 ulp of the exact value, finite up to the overflow past 710.47), the double's rounded once of a float one (detail::through_doubles, within half an ulp and 2⁻²⁸).

Definition at line 2694 of file tensor_ops.hpp.

◆ count_nonzero() [1/2]

template<typename T >
std::size_t numerical::count_nonzero ( const tensor< T > &  t)

The number of nonzero elements (x != T {}: a NaN is one), as numpy.count_nonzero without an axis: by chunks on the threads, each chunk's counted without a branch, then the counts summed; a transpose's as its elements lie (tensor::laid_out), none copied.

Definition at line 4501 of file tensor_ops.hpp.

◆ count_nonzero() [2/2]

template<typename T >
tensor< std::int64_t > numerical::count_nonzero ( const tensor< T > &  t,
std::size_t  axis 
)

The number of nonzero elements (x != T {}) along axis, as numpy.count_nonzero.

Exceptions
dimension_errorIf axis is not an axis.

Definition at line 4525 of file tensor_ops.hpp.

◆ cumprod()

template<typename T >
tensor< T > numerical::cumprod ( const tensor< T > &  t,
std::size_t  axis 
)

The running products along axis, in order, as numpy.cumprod.

Exceptions
dimension_errorIf axis is not an axis.

Definition at line 3489 of file tensor_ops.hpp.

◆ cumsum()

template<typename T >
tensor< T > numerical::cumsum ( const tensor< T > &  t,
std::size_t  axis 
)

The running sums along axis, in order, as numpy.cumsum.

Exceptions
dimension_errorIf axis is not an axis.

Definition at line 3477 of file tensor_ops.hpp.

◆ dct()

template<std::floating_point T>
tensor< T > numerical::dct ( const tensor< T > &  a,
int  type = 2,
std::optional< std::size_t >  n = std::nullopt,
std::ptrdiff_t  axis = -1,
fft_norm  norm = fft_norm::backward,
std::optional< bool >  orthogonalize = std::nullopt 
)

The discrete cosine transform of real a along axis, as scipy.fft.dct: type 2 by default, y_k = 2 Σ_j x_j cos(πk(2j + 1)/2n); type 1 x_0 + (−1)^k x_{n−1} + 2 Σ_{0<j<n−1} x_j cos(πjk/(n − 1)); type 3 x_0 + 2 Σ_{j>0} x_j cos(πj(2k + 1)/2n); type 4 2 Σ_j x_j cos(π(2j + 1)(2k + 1)/4n). By a Fourier transform of n points (2(n − 1) for type 1).

Parameters
[in]aA tensor of float or double.
[in]type1, 2, 3 or 4.
[in]nThe points: the axis cut to them, or padded with zeros; its extent by default.
[in]axisThe axis transformed, negative from the last (the last by default).
[in]normThe scaling: none by default; ortho 1/√(2n) (1/√(2(n − 1)) for type 1), forward its square.
[in]orthogonalizeThe first (type 1 also the last) point and value weighted to make the matrix orthogonal, as SciPy's: by default where norm is ortho.
Exceptions
argument_errorIf type is not 1 to 4.
dimension_errorIf axis is not an axis of a, or n is 0 (1 for type 1).

Definition at line 3574 of file fft.hpp.

◆ determinant()

template<field T>
T numerical::determinant ( matrix< T >  a)

The determinant of a square matrix.

Exceptions
dimension_errorIf not square.

Definition at line 1813 of file factorizations.hpp.

◆ diag()

template<typename T >
tensor< T > numerical::diag ( const tensor< T > &  v,
std::ptrdiff_t  k 
)

The square matrix with the vector v on its k diagonal (above the main one for a positive k) and zeros elsewhere, as numpy.diag of a vector: of order len v + |k|.

Exceptions
dimension_errorIf v is not a vector, or the square's size overflows.

Definition at line 5149 of file tensor_ops.hpp.

◆ diagonal()

template<typename T >
tensor< T > numerical::diagonal ( const tensor< T > &  t,
std::ptrdiff_t  offset 
)

The offset diagonal of each matrix of t (its last two axes), as numpy.linalg.diagonal: above the main diagonal for a positive offset, below for a negative one: a view (tensor::diagonal_view), no element copied but a few; the batch's shape, then the diagonal's length (0 where offset passes the matrix).

Exceptions
dimension_errorIf t has fewer than two axes.

Definition at line 5009 of file tensor_ops.hpp.

◆ dot()

template<typename T >
T numerical::dot ( const vector< T > &  a,
const vector< T > &  b 
)

Dot product.

Exceptions
dimension_errorIf the sizes differ.

Definition at line 275 of file vector.hpp.

◆ dst()

template<std::floating_point T>
tensor< T > numerical::dst ( const tensor< T > &  a,
int  type = 2,
std::optional< std::size_t >  n = std::nullopt,
std::ptrdiff_t  axis = -1,
fft_norm  norm = fft_norm::backward,
std::optional< bool >  orthogonalize = std::nullopt 
)

The discrete sine transform of real a along axis, as scipy.fft.dst: type 2 by default, y_k = 2 Σ_j x_j sin(π(k + 1)(2j + 1)/2n); type 1 2 Σ_j x_j sin(π(j + 1)(k + 1)/(n + 1)); type 3 (−1)^k x_{n−1} + 2 Σ_{j<n−1} x_j sin(π(j + 1)(2k + 1)/2n); type 4 2 Σ_j x_j sin(π(2j + 1)(2k + 1)/4n). Type 1 by a real Fourier transform of 2(n + 1) points, the others by dct's.

Parameters
[in]aA tensor of float or double.
[in]type1, 2, 3 or 4.
[in]nThe points: the axis cut to them, or padded with zeros; its extent by default.
[in]axisThe axis transformed, negative from the last (the last by default).
[in]normThe scaling: none by default; ortho 1/√(2n) (1/√(2(n + 1)) for type 1), forward its square.
[in]orthogonalizeThe last point (type 3) or value (type 2) weighted to make the matrix orthogonal, as SciPy's: by default where norm is ortho.
Exceptions
argument_errorIf type is not 1 to 4.
dimension_errorIf axis is not an axis of a, or n is 0.

Definition at line 3617 of file fft.hpp.

◆ eigenvalues()

template<field T>
vector< std::complex< double > > numerical::eigenvalues ( const matrix< T > &  a)

The eigenvalues alone of the square a, as numpy.linalg.eigvals.

Exceptions
dimension_errorIf a is not square.
non_finite_errorIf an entry is infinite or NaN.
convergence_errorIf the QR iterations did not converge.

Definition at line 3686 of file eigen.hpp.

◆ einsum() [1/2]

template<typename T >
tensor< T > numerical::einsum ( const std::string &  spec,
const std::vector< const tensor< T > * > &  operands 
)

Einstein summation over operands counted at run time: einsum for a caller that holds them in a container (an interpreter evaluating einsum("ij,jk->ik", a, b) from a parse).

Parameters
[in]specThe einsum specification.
[in]operandsThe operands, in the spec's order (none null).
Returns
The resulting tensor.
Exceptions
einsum_errorAs einsum, and if operands is empty.
dimension_errorAs einsum.

Definition at line 2778 of file tensor.hpp.

◆ einsum() [2/2]

template<typename T , typename ... Rest>
tensor< T > numerical::einsum ( const std::string &  spec,
const tensor< T > &  first,
const Rest &...  rest 
)

Einstein summation over one or more tensor operands.

Evaluates spec — input subscripts separated by ,, then ->, then the output subscripts — against the operands. Examples: "ij,jk->ik" (matrix product), "i,i->" (dot product), "ij->ji" (transpose), "ii->" (trace), "i,j->ij" (outer product), "ij->i" (row sums).

Parameters
[in]specThe einsum specification.
[in]firstThe first operand (fixes the scalar type).
[in]restAny further operands.
Returns
The resulting tensor (rank-0 when the output subscripts are empty).
Exceptions
einsum_errorIf the spec is malformed, the operand count or a rank disagrees with it, or an output label is invalid.
dimension_errorIf a shared label labels axes of differing extents.

Definition at line 2760 of file tensor.hpp.

◆ environment_threads()

std::size_t numerical::environment_threads ( const char *  numerical,
const char *  omp 
)
inlineprivatenoexcept

The cap of threads the environment asks for, as the Python package and OpenBLAS read it: numerical (NUMERICAL_NUM_THREADS's value) where it is set and not blank, else the first count of omp (OMP_NUM_THREADS's, which joblib and loky set in their workers); null for an unset variable. 0 (no cap) where neither gives a count, or for one that is not a run of digits; above 2³¹, 2³¹.

Definition at line 964 of file parallel.hpp.

◆ exp()

template<typename T >
tensor< T > numerical::exp ( const tensor< T > &  a)

exp of every element: detail::exp_into of a double one (within 0.506 ulp of the exact value), std::exp of a float one, detail::complex_exp of a complex one.

Definition at line 2654 of file tensor_ops.hpp.

◆ exp2()

template<std::floating_point T>
tensor< T > numerical::exp2 ( const tensor< T > &  a)

2^x of every real element: detail::exp2_into of a double one (within 0.506 ulp of the exact value where it is normal, exact at every integer), std::exp2 of a float one.

Definition at line 2704 of file tensor_ops.hpp.

◆ expm()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > numerical::expm ( const matrix< T > &  a)

The exponential e^A of a square matrix, as scipy.linalg.expm: scaling and squaring of a Padé approximant, as Al-Mohy and Higham's algorithm (2009): the degree 3, 5, 7, 9 or 13 and the squarings s chosen from ‖A^{2k}‖₁^{1/2k} (exact, A², A⁴ and A⁶ formed, A⁸ and A¹⁰ where needed) and the approximant's backward error bound (ℓ), then r(2⁻ˢ A) squared s times; an upper triangular A's diagonal and first superdiagonal written exactly at each squaring. A Hermitian A (to the bit) of order hermitian_expm_least or more: V e^Λ Vᴴ from its eigendecomposition.

Template Parameters
Tdouble or std::complex<double> (the degrees' bounds are double precision's).
Exceptions
dimension_errorIf a is not square.
non_finite_errorIf an entry is infinite or NaN.

Definition at line 395 of file matrix_functions.hpp.

◆ expm1()

template<std::floating_point T>
tensor< T > numerical::expm1 ( const tensor< T > &  a)

exp(x) − 1 of every real element, exact near 0: detail::expm1_into of a double one (within 0.503 ulp of the exact value), the double's rounded once of a float one (detail::through_doubles, within half an ulp and 2⁻²⁸).

Definition at line 2664 of file tensor_ops.hpp.

◆ expm_cond()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
double numerical::expm_cond ( const matrix< T > &  a)

The relative condition number of the exponential at a in the Frobenius norm, as scipy.linalg.expm_cond: ‖K‖₂ ‖A‖_F / ‖e^A‖_F, K the n² × n² Kronecker form of the Fréchet derivative (its column i n + j the column-major vec of L(A, eᵢ eⱼᵀ)), ‖K‖₂ its largest singular value. An empty matrix's is 0.

Exceptions
dimension_errorIf a is not square.
non_finite_errorIf an entry is infinite or NaN.

Definition at line 1172 of file matrix_functions.hpp.

◆ expm_frechet()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
std::pair< matrix< T >, matrix< T > > numerical::expm_frechet ( const matrix< T > &  a,
const matrix< T > &  e,
frechet_method  method = frechet_method::scaling_pade_squaring 
)

e^A and the Fréchet derivative L(A, E) of the exponential at a along e, as scipy.linalg.expm_frechet: by default Al-Mohy and Higham's algorithm 6.4 (2009) as SciPy's: the [m/m] Padé approximant (m 3, 5, 7 or 9) where ‖A‖₁ is within its bound, else m = 13 on 2⁻ˢ A and 2⁻ˢ E, s = ⌈log₂(‖A‖₁ / 4.74)⌉, then s squarings L ← R L + L R, R ← R²; or the exponential of [[A, E], [0, A]], whose blocks are e^A and L(A, E).

Template Parameters
Tdouble or std::complex<double>.
Exceptions
dimension_errorIf a or e is not square or their orders differ.
non_finite_errorIf an entry is infinite or NaN.
singular_matrix_errorIf the approximant's denominator is singular.

Definition at line 1106 of file matrix_functions.hpp.

◆ expm_multiply()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > numerical::expm_multiply ( const matrix< T > &  a,
const matrix< T > &  b,
double  t = 1.0 
)

e^{tA} B without forming e^{tA}, as scipy.sparse.linalg.expm_multiply: Al-Mohy and Higham's algorithm 3.2 (2011). A less μ I, μ its trace over n; then s steps, each m terms at most of the Taylor series of e^{tA/s} on the step's start, each term one product of A by the n × k block (the matrix product kernel), the series stopped where its last two terms fall under the unit roundoff of the sum; each step times e^{tμ/s}. m and s the least products for the unit roundoff (detail::plan_taylor), the norms of A's powers estimated through products with vectors (detail::one_norm_estimate). Some m s products of n² k where e^{tA} takes n³ several times: the few columns' case.

Parameters
[in]aThe square matrix.
[in]bThe block it acts on (n × k).
[in]tThe time.
Returns
e^{tA} B (n × k).
Exceptions
dimension_errorIf a is not square or b has not its rows.
non_finite_errorIf an entry of a or b, or t, is infinite or NaN.

Definition at line 618 of file matrix_functions.hpp.

◆ eye()

template<typename T >
tensor< T > numerical::eye ( std::size_t  n)

The n × n identity.

Definition at line 5179 of file tensor_ops.hpp.

◆ fft() [1/2]

template<detail::fft_input T>
requires detail::split_complex<T>
tensor< T > numerical::fft ( const tensor< T > &  a,
std::optional< std::size_t >  n = std::nullopt,
std::ptrdiff_t  axis = -1,
fft_norm  norm = fft_norm::backward 
)

The discrete Fourier transform of a along axis, as numpy.fft.fft: X_k = Σ_j x_j e^{−2πi jk/n}.

Parameters
[in]aA tensor of complex float or double (a real one: the overload of real tensors).
[in]nThe points transformed: the axis cut to them, or padded with zeros; its extent by default.
[in]axisThe axis transformed, negative from the last (the last by default).
[in]normThe scaling (fft_norm): none by default.
Returns
The complex transform, of a's shape with the axis n long.
Exceptions
dimension_errorIf axis is not an axis of a, or n is 0.

Definition at line 2966 of file fft.hpp.

◆ fft() [2/2]

template<std::floating_point T>
tensor< std::complex< T > > numerical::fft ( const tensor< T > &  a,
std::optional< std::size_t >  n = std::nullopt,
std::ptrdiff_t  axis = -1,
fft_norm  norm = fft_norm::backward 
)

The discrete Fourier transform of real a along axis, as numpy.fft.fft of a real array: its non-negative frequencies by the real transform (rfft's), the others by their Hermitian symmetry, X_{n−k} = conj X_k exactly; a length whose complex transform takes four steps (four_step_plan) as a complex one, on the threads.

Parameters
[in]aA tensor of float or double.
[in]nThe points transformed: the axis cut to them, or padded with zeros; its extent by default.
[in]axisThe axis transformed, negative from the last (the last by default).
[in]normThe scaling (fft_norm): none by default.
Returns
The complex transform, of a's shape with the axis n long.
Exceptions
dimension_errorIf axis is not an axis of a, or n is 0.

Definition at line 2989 of file fft.hpp.

◆ fftshift() [1/2]

template<typename T >
tensor< T > numerical::fftshift ( const tensor< T > &  a,
const std::vector< std::ptrdiff_t > &  axes,
bool  inverse = false 
)

a with its axes axes rolled so that each one's element 0 lands at its middle, as numpy.fft.fftshift: element j of each to (j + n/2) mod n, an axis given twice rolled twice; or back, as numpy.fft.ifftshift, where inverse. In one copy, whatever the axes.

Parameters
[in]aAny tensor.
[in]axesThe axes rolled, negative from the last.
[in]inverseifftshift's roll, by −(n/2), where an odd extent makes it differ.
Returns
The rolled copy, of a's shape.
Exceptions
dimension_errorIf an axis is not one of a.

Definition at line 3100 of file fft.hpp.

◆ fftshift() [2/2]

template<typename T >
tensor< T > numerical::fftshift ( const tensor< T > &  a,
std::ptrdiff_t  axis = -1,
bool  inverse = false 
)

a with its axis axis rolled so that its element 0 lands at its middle, as numpy.fft.fftshift along one axis: element j to (j + n/2) mod n; or back, as numpy.fft.ifftshift, where inverse.

Parameters
[in]aAny tensor.
[in]axisThe axis rolled, negative from the last.
[in]inverseifftshift's roll, by −(n/2), where an odd extent makes it differ.
Returns
The rolled copy, of a's shape.
Exceptions
dimension_errorIf axis is not an axis of a.

Definition at line 3127 of file fft.hpp.

◆ finish_funm()

funm_result numerical::finish_funm ( const funm_plan &  plan,
const std::vector< std::complex< double > > &  images 
)
inline

f(A) from its funm_plan and images, f at the plan's points: a Hermitian A's V f(Λ) Vᴴ, its estimate ε; where eigenvalues gather, Davies and Higham's Schur–Parlett algorithm with each cluster by Cauchy's integral (detail::clustered_function); else Parlett's recurrence, as SciPy's (funm_from_schur). The estimate ∞ where f at an eigenvalue, or the result, is not finite.

Exceptions
dimension_errorIf images does not hold one value per point.

Definition at line 2441 of file matrix_functions.hpp.

◆ floor_divide()

template<typename T >
tensor< T > numerical::floor_divide ( const tensor< T > &  a,
const tensor< T > &  b 
)

a // b element by element, broadcast, as numpy.floor_divide (detail::floor_divmod).

Exceptions
dimension_errorIf the shapes do not broadcast.

Definition at line 3119 of file tensor_ops.hpp.

◆ fractional_matrix_power()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< std::complex< double > > numerical::fractional_matrix_power ( const matrix< T > &  a,
double  p 
)

A^p for a real p, as scipy.linalg.fractional_matrix_power: a whole p by repeated squaring; for p > 0, an exactly Hermitian (real symmetric) A by one eigendecomposition, V Λᵖ Vᴴ (Hermitian where no eigenvalue is below 0); else A^a A^b with a the floor or the ceiling of p, chosen by A's condition as SciPy chooses it, and A^b (|b| < 1) by Higham and Lin's Schur–Padé algorithm (2013) on the Schur form. Where the triangular form has a zero on its diagonal (A singular), a positive p falls back to funm of x^(p − ⌊p⌋), as SciPy's; a negative one has no answer and is refused (SciPy returns a matrix of NaN). Complex: a real matrix's power may be complex.

Template Parameters
Tdouble or std::complex<double>.
Exceptions
dimension_errorIf a is not square.
non_finite_errorIf an entry is infinite or NaN.
argument_errorIf p is infinite or NaN.
singular_matrix_errorIf p is negative and a singular.
convergence_errorIf a Schur form's iterations did not converge, or the square roots of its triangular form are not finite.

Definition at line 3379 of file matrix_functions.hpp.

◆ full()

template<typename T >
tensor< T > numerical::full ( std::vector< std::size_t >  shape,
const T &  value 
)

A tensor of shape with every element value.

Definition at line 5118 of file tensor_ops.hpp.

◆ funm()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
funm_result numerical::funm ( const matrix< T > &  a,
const std::function< std::vector< std::complex< double > >(const std::vector< std::complex< double > > &)> &  f 
)

A function of a square matrix, as scipy.linalg.funm: plan_funm, f called once with the plan's points (the eigenvalues, then the circles' where eigenvalues gather) returning one value each, then finish_funm. f must be analytic on each circle's disk. Accurate where the eigenvalues are well apart or gather tightly; between, Parlett's recurrence (the estimate says how).

Template Parameters
Tdouble or std::complex<double>.
Exceptions
dimension_errorIf a is not square, or f does not return one value per point.
non_finite_errorIf an entry is infinite or NaN.
convergence_errorIf the Schur form's iterations did not converge.

Definition at line 2510 of file matrix_functions.hpp.

◆ funm_from_schur()

funm_result numerical::funm_from_schur ( const matrix< std::complex< double > > &  t,
const matrix< std::complex< double > > &  z,
const std::vector< std::complex< double > > &  values 
)
inline

f(A) from the complex Schur form A = Z T Zᴴ and f at T's diagonal (values), as scipy.linalg.funm completes it: Parlett's recurrence (Golub and Van Loan's algorithm 11.1.1) on F, a superdiagonal at a time, F(i, j) = (T(i, j) (F(j, j) − F(i, i)) + Σ T(i, k) F(k, j) − Σ F(i, k) T(k, j)) / (T(j, j) − T(i, i)) (not divided where two diagonal entries are equal, as SciPy's, the error estimate then 1), then Z F Zᴴ. The estimate: the recurrence run again on its roundings (detail::recurrence_error), or SciPy's where larger, δ the smallest |T(j, j) − T(i, i)| met (or |T(0, 0)|, ε where 0); SciPy's alone said 6·10⁻¹⁴ of an error of 2·10⁻¹¹ (order 16, eigenvalues 0.27 apart, T's strict upper triangle 5 N(0, 1)).

Exceptions
dimension_errorIf t and z are not square of one order or values does not hold n entries.

Definition at line 1864 of file matrix_functions.hpp.

◆ funm_points()

std::vector< std::complex< double > > numerical::funm_points ( const funm_plan &  plan)
inline

The points where finish_funm wants f for plan (not Hermitian) with its circles' counts: its eigenvalues, then each circle's.

Definition at line 2472 of file matrix_functions.hpp.

◆ gemm_path_in_use()

gemm_path numerical::gemm_path_in_use ( )
inlinenoexcept

The path double matrix products take.

Definition at line 5356 of file gemm.hpp.

◆ generalized_eigenvectors() [1/2]

matrix< std::complex< double > > numerical::generalized_eigenvectors ( const generalized_schur &  d,
bool  left 
)
inline

The right (or, where left, the left) eigenvectors of the pencil d decomposes, as LAPACK's ztgevc and scipy.linalg.eig(a, b): for each eigenvalue (α, β) in the diagonals' order, x with (β S − α T) x = 0 and x_k = 1 by back substitution (yᴴ (β S − α T) = 0 forward for a left one), then Z x (Q y) made of unit 2-norm, as SciPy normalises ggev's; a diagonal entry of β S − α T below ε (|β| ‖S‖ + |α| ‖T‖) taken as that bound (ztgevc's SMIN, at least the smallest normal number), and an eigenvalue with α and β both zero (a singular pencil) given the unit vector of its place, as ztgevc gives it.

Returns
The vectors as columns.

Definition at line 2414 of file generalized.hpp.

◆ generalized_eigenvectors() [2/2]

matrix< std::complex< double > > numerical::generalized_eigenvectors ( const real_generalized_schur &  d,
bool  left 
)
inline

The right (or, where left, the left) eigenvectors of the real pencil d decomposes, complex, as scipy.linalg.eig(a, b) gives them for a real pencil (each of unit 2-norm): each 2 × 2 block of S and T made triangular first by unitary rotations from both sides (the left one along T v, the right one along the block's eigenvector v), carried through S, T, Q and Z, then the complex pencil's vectors (generalized_eigenvectors). The columns in the diagonals' order, as d's values.

Definition at line 2593 of file generalized.hpp.

◆ hankel()

template<typename T >
matrix< T > numerical::hankel ( const vector< T > &  c,
const vector< T > &  r 
)

The m × n Hankel matrix of first column c (m entries) and last row r (n), as scipy.linalg.hankel: H(i, j) = c[i + j] while i + j < m, r[i + j − m + 1] past it (r[0] not read).

Definition at line 877 of file banded.hpp.

◆ hermitian_eigen_subset()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
eigen_subset< T > numerical::hermitian_eigen_subset ( const matrix< T > &  a,
std::size_t  first,
std::size_t  last,
bool  vectors = true 
)

The eigenvalues of indices first to last (ascending, from 0) of the real symmetric or complex Hermitian a, its lower triangle read, and their eigenvectors where vectors, as scipy.linalg.eigh(a, subset_by_index=[first, last]): the tridiagonal form (LAPACK's sytrd, hetrd), the eigenvalues by bisection (tridiagonal_eigenvalues, stebz), the vectors by inverse iteration (detail::inverse_iteration, stein) taken back through the reflections (ormtr, unmtr): past the reduction, n² k operations where the whole spectrum's vectors take n³ and more. On the matrix divided by the power of two of its largest magnitude. Where an iterate does not converge or a cluster of eigenvalues is too large, the vectors are the whole spectrum's by divide and conquer.

Exceptions
dimension_errorIf a is not square, or first > last or last ≥ n.
non_finite_errorIf an entry of the lower triangle is infinite or NaN.

Definition at line 2978 of file svd.hpp.

◆ hermitian_eigen_subset_by_value()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
eigen_subset< T > numerical::hermitian_eigen_subset_by_value ( const matrix< T > &  a,
double  low,
double  high,
bool  vectors = true 
)

hermitian_eigen_subset of the eigenvalues in (low, high], as scipy.linalg.eigh(a, subset_by_value=[low, high]): their indices by Sturm's counts on the tridiagonal form (tridiagonal_eigenvalue_range); none, the vectors n × 0.

Exceptions
dimension_errorIf a is not square.
non_finite_errorIf an entry of the lower triangle is infinite or NaN.

Definition at line 3000 of file svd.hpp.

◆ hfft()

template<std::floating_point T>
tensor< T > numerical::hfft ( const tensor< std::complex< T > > &  a,
std::optional< std::size_t >  n = std::nullopt,
std::ptrdiff_t  axis = -1,
fft_norm  norm = fft_norm::backward 
)

The transform of a signal of Hermitian symmetry, its n real points from the non-negative frequencies a, as numpy.fft.hfft: irfft of conj(a), its scaling's direction exchanged.

Parameters
[in]aA tensor of complex float or double.
[in]nThe real points: 2·(m − 1) by default.
[in]axisThe axis transformed, negative from the last.
[in]normThe scaling (fft_norm): none by default.
Returns
The real transform.
Exceptions
dimension_errorIf axis is not an axis of a, or n is 0.

Definition at line 3191 of file fft.hpp.

◆ idct()

template<std::floating_point T>
tensor< T > numerical::idct ( const tensor< T > &  a,
int  type = 2,
std::optional< std::size_t >  n = std::nullopt,
std::ptrdiff_t  axis = -1,
fft_norm  norm = fft_norm::backward,
std::optional< bool >  orthogonalize = std::nullopt 
)

The inverse of dct of the same type, as scipy.fft.idct: the transform of type 3 for type 2 and of type 2 for type 3 (types 1 and 4 their own), scaled by 1/2n (1/2(n − 1) for type 1) by default.

Parameters
[in]aA tensor of float or double.
[in]type1, 2, 3 or 4.
[in]nThe points: the axis cut to them, or padded with zeros; its extent by default.
[in]axisThe axis transformed, negative from the last (the last by default).
[in]normThe scaling: none by default; ortho 1/√(2n) (1/√(2(n − 1)) for type 1), forward its square.
[in]orthogonalizeThe first (type 1 also the last) point and value weighted to make the matrix orthogonal, as SciPy's: by default where norm is ortho.
Exceptions
argument_errorIf type is not 1 to 4.
dimension_errorIf axis is not an axis of a, or n is 0 (1 for type 1).

Definition at line 3590 of file fft.hpp.

◆ idst()

template<std::floating_point T>
tensor< T > numerical::idst ( const tensor< T > &  a,
int  type = 2,
std::optional< std::size_t >  n = std::nullopt,
std::ptrdiff_t  axis = -1,
fft_norm  norm = fft_norm::backward,
std::optional< bool >  orthogonalize = std::nullopt 
)

The inverse of dst of the same type, as scipy.fft.idst: the transform of type 3 for type 2 and of type 2 for type 3 (types 1 and 4 their own), scaled by 1/2n (1/2(n + 1) for type 1) by default.

Parameters
[in]aA tensor of float or double.
[in]type1, 2, 3 or 4.
[in]nThe points: the axis cut to them, or padded with zeros; its extent by default.
[in]axisThe axis transformed, negative from the last (the last by default).
[in]normThe scaling: none by default; ortho 1/√(2n) (1/√(2(n + 1)) for type 1), forward its square.
[in]orthogonalizeThe last point (type 3) or value (type 2) weighted to make the matrix orthogonal, as SciPy's: by default where norm is ortho.
Exceptions
argument_errorIf type is not 1 to 4.
dimension_errorIf axis is not an axis of a, or n is 0.

Definition at line 3633 of file fft.hpp.

◆ ifft() [1/2]

template<detail::fft_input T>
requires detail::split_complex<T>
tensor< T > numerical::ifft ( const tensor< T > &  a,
std::optional< std::size_t >  n = std::nullopt,
std::ptrdiff_t  axis = -1,
fft_norm  norm = fft_norm::backward 
)

The inverse discrete Fourier transform of a along axis, as numpy.fft.ifft: x_j = (1/n) Σ_k X_k e^{2πi jk/n} with the default norm.

Parameters
[in]aA tensor of float, double or their complex numbers.
[in]nThe points transformed: the axis cut to them, or padded with zeros; its extent by default.
[in]axisThe axis transformed, negative from the last (the last by default).
[in]normThe scaling (fft_norm): 1/n by default.
Returns
The complex inverse transform, of a's shape with the axis n long.
Exceptions
dimension_errorIf axis is not an axis of a, or n is 0.

Definition at line 3011 of file fft.hpp.

◆ ifft() [2/2]

template<std::floating_point T>
tensor< std::complex< T > > numerical::ifft ( const tensor< T > &  a,
std::optional< std::size_t >  n = std::nullopt,
std::ptrdiff_t  axis = -1,
fft_norm  norm = fft_norm::backward 
)

The inverse discrete Fourier transform of real a along axis, as numpy.fft.ifft of a real array: the conjugate of its transform (fft of a real tensor), scaled as the inverse.

Parameters
[in]aA tensor of float or double.
[in]nThe points transformed: the axis cut to them, or padded with zeros; its extent by default.
[in]axisThe axis transformed, negative from the last (the last by default).
[in]normThe scaling (fft_norm): 1/n by default.
Returns
The complex inverse transform, of a's shape with the axis n long.
Exceptions
dimension_errorIf axis is not an axis of a, or n is 0.

Definition at line 3032 of file fft.hpp.

◆ ihfft()

template<std::floating_point T>
tensor< std::complex< T > > numerical::ihfft ( const tensor< T > &  a,
std::optional< std::size_t >  n = std::nullopt,
std::ptrdiff_t  axis = -1,
fft_norm  norm = fft_norm::backward 
)

The inverse of hfft, as numpy.fft.ihfft: conj(rfft(a)), its scaling's direction exchanged.

Parameters
[in]aA tensor of float or double.
[in]nThe points transformed: the axis' extent by default.
[in]axisThe axis transformed, negative from the last.
[in]normThe scaling (fft_norm): 1/n by default.
Returns
The n/2 + 1 complex frequencies.
Exceptions
dimension_errorIf axis is not an axis of a, or n is 0.

Definition at line 3210 of file fft.hpp.

◆ inverse()

template<field T>
matrix< T > numerical::inverse ( matrix< T >  a)

The inverse of a square matrix.

Parameters
[in]aThe matrix.
Returns
Its inverse.
Exceptions
dimension_errorIf a is not square.
singular_matrix_errorIf a is singular.

Definition at line 1826 of file factorizations.hpp.

◆ irfft()

template<std::floating_point T>
tensor< T > numerical::irfft ( const tensor< std::complex< T > > &  a,
std::optional< std::size_t >  n = std::nullopt,
std::ptrdiff_t  axis = -1,
fft_norm  norm = fft_norm::backward 
)

The inverse of rfft along axis, as numpy.fft.irfft: n real points from the first n/2 + 1 frequencies of a (cut, or padded with zeros), the imaginary parts of the zero frequency and of an even n's last read as 0.

Parameters
[in]aA tensor of complex float or double.
[in]nThe real points: 2·(m − 1) by default, m the axis' extent.
[in]axisThe axis transformed, negative from the last (the last by default).
[in]normThe scaling (fft_norm): 1/n by default.
Returns
The real inverse transform, of a's shape with the axis n long.
Exceptions
dimension_errorIf axis is not an axis of a, or n is 0.

Definition at line 3166 of file fft.hpp.

◆ least_squares()

template<typename T >
least_squares_solution< T > numerical::least_squares ( const matrix< T > &  a,
const matrix< T > &  b,
rank_cutoff  cutoff = {} 
)

lstsq, with the residuals, the rank and the singular values numpy.linalg.lstsq returns beside the solution: the residual sums of squares are given only where the solution is unique and need not be exact, A tall (m > n) and of full column rank, as NumPy gives them.

Parameters
[in]aThe m × n matrix.
[in]bThe right-hand sides (m × k).
[in]cutoffWhere a singular value counts as zero, in the solution and the rank.
Exceptions
dimension_errorIf b's rows differ from a's.
non_finite_errorIf an entry of a is infinite or NaN.

Definition at line 3031 of file svd.hpp.

◆ limit_gemm_path()

gemm_path numerical::limit_gemm_path ( gemm_path  most)
inlinenoexcept

Keeps double matrix products on most or a more portable path: the most capable path at or below it that can run here. gemm_path::amx restores the best one; gemm_path::portable keeps them on the compiler's own vectors, with no instruction chosen at run time. Paths below the cap are not probed.

Returns
The path now in use.

Definition at line 5349 of file gemm.hpp.

◆ linspace()

tensor< double > numerical::linspace ( double  start,
double  stop,
std::size_t  count 
)
inline

count values evenly spaced from start to stop, both included, as NumPy's linspace: element i is start + i·step with step = (stop − start) / (count − 1), and the last is stop exactly.

Definition at line 5238 of file tensor_ops.hpp.

◆ log()

template<typename T >
tensor< T > numerical::log ( const tensor< T > &  a)

log of every element: std::log of a real one, detail::complex_log of a complex one.

Definition at line 2711 of file tensor_ops.hpp.

◆ log1p()

template<std::floating_point T>
tensor< T > numerical::log1p ( const tensor< T > &  a)

log(1 + x) of every real element, exact near 0: detail::log1p_into of a double one (within 0.501 ulp of the exact value), the double's rounded once of a float one (detail::through_doubles, within half an ulp and 2⁻²⁸).

Definition at line 2721 of file tensor_ops.hpp.

◆ logm()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
logm_result numerical::logm ( const matrix< T > &  a)

The principal logarithm of a square matrix, as scipy.linalg.logm: an upper triangular A directly, else its Schur form A = Z T Zᴴ and Z log(T) Zᴴ: in real arithmetic where A is real and its real Schur form triangular with no eigenvalue below 0, else in the complex form (the real one made complex), as SciPy's. log T by Al-Mohy and Higham's inverse scaling and squaring (2012) as SciPy's _logm_triu, the norms that choose the square roots and the degree exact where SciPy estimates them. A zero eigenvalue is taken as 10⁻²⁰ (no logarithm exists there), as SciPy's, and reported; complex, SciPy's real part where A is real and it is negligible.

Template Parameters
Tdouble or std::complex<double>.
Exceptions
dimension_errorIf a is not square.
non_finite_errorIf an entry is infinite or NaN.
convergence_errorIf the Schur form's iterations did not converge, or the square roots of its triangular form are not finite.

Definition at line 3523 of file matrix_functions.hpp.

◆ lstsq() [1/2]

template<field T>
matrix< T > numerical::lstsq ( const matrix< T > &  a,
const matrix< T > &  b,
rank_cutoff  cutoff = {} 
)

The minimum-norm least-squares solution of A X ≈ B for every column of B at once, as numpy.linalg.lstsq with a matrix right-hand side: one SVD of A, X = V Σ⁺ Uᴴ B; or, where a bound on the condition number shows the rank full with room to spare, the same solution to rounding by one QR factorisation (detail::lstsq_by_qr).

Template Parameters
TThe scalar element type (double or std::complex<double>).
Parameters
[in]aThe m × n matrix.
[in]bThe right-hand sides (m × k).
[in]cutoffWhere a singular value counts as zero.
Returns
X (n × k).
Exceptions
dimension_errorIf b's row count differs from a's.
non_finite_errorIf an entry of a is infinite or NaN.

Definition at line 2248 of file svd.hpp.

◆ lstsq() [2/2]

template<field T>
vector< T > numerical::lstsq ( const matrix< T > &  a,
const vector< T > &  b,
rank_cutoff  cutoff = {} 
)

The minimum-norm least-squares solution of A x ≈ b, as NumPy's lstsq gives it.

Template Parameters
TThe scalar element type (double or std::complex<double>).

From the SVD of A: x = V Σ⁺ Uᴴ b, where a singular value at or under cutoff (by default NumPy's, rank_cutoff) counts as zero. Any shape, any rank: an overdetermined full-rank system gives its least-squares solution, an underdetermined or rank-deficient one the solution of smallest norm.

Parameters
[in]aThe m × n matrix.
[in]bThe right-hand side (size m).
[in]cutoffWhere a singular value counts as zero.
Returns
x (size n).
Exceptions
dimension_errorIf b's size differs from the row count.
non_finite_errorIf an entry of a is infinite or NaN.

Definition at line 2226 of file svd.hpp.

◆ lu_factors()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
rectangular_lu< T > numerical::lu_factors ( const matrix< T > &  a)

The pivoted LU factorisation A = P L U of an m × n matrix, as scipy.linalg.lu: L m × k lower trapezoidal with a unit diagonal, U k × n upper trapezoidal, k = min(m, n), rows chosen by partial pivoting. A wide matrix's square part by lu_decomposition and U's other columns by L⁻¹ P A (a triangular solve); a tall one by lu_decomposition of it beside zero columns (its first n columns factorised alike) up to detail::lu_tall_ratio times as tall as wide, by dgetrf2's recursion over its columns (detail::tall_lu_columns) past. A zero pivot leaves its column of L zero, as LAPACK's.

Template Parameters
Tdouble or std::complex<double>.
Exceptions
non_finite_errorIf an entry is infinite or NaN.

Definition at line 2507 of file factorizations.hpp.

◆ map()

template<typename T , typename F >
auto numerical::map ( const tensor< T > &  t,
const F &  f 
) -> tensor<std::decay_t<decltype(f(std::declval<const T&>()))>>

f(x) for every element, in a tensor of the same shape and of f's result type.

Definition at line 3144 of file tensor_ops.hpp.

◆ matmul()

template<typename T >
tensor< T > numerical::matmul ( const tensor< T > &  a,
const tensor< T > &  b 
)

The matrix product of two tensors, as NumPy's matmul: each operand a stack of matrices along its leading axes, those axes broadcast against the other's (aligned from the right, an extent of 1 repeated), one product per matrix of the broadcast stack through the packed kernel, the products in parallel. A vector first is a row (its axis absent from the result), a vector second a column (likewise); two vectors give their dot product, of rank 0. The broadcast operands are not copied: a repeated matrix is read where it is.

matmul of a signed integer type: through its unsigned type, wrapped as NumPy's (detail::einsum_impl).

Parameters
[in]a,bThe operands, of rank 1 or more.
Returns
a @ b, of the broadcast leading axes, then the rows of a and the columns of b.
Exceptions
dimension_errorIf an operand is of rank 0, the inner extents differ, or the leading axes do not broadcast.

Definition at line 2884 of file tensor.hpp.

◆ matrix_balance()

template<typename T >
balanced_matrix< T > numerical::matrix_balance ( const matrix< T > &  a,
bool  permute = true,
bool  scale = true 
)

The square a balanced, as scipy.linalg.matrix_balance(a, permute, scale, separate=True) (LAPACK's dgebal): B = T⁻¹ A T, T = P D a permutation (permute: rows and columns isolating an eigenvalue moved to the ends) times powers of two (scale: the remaining block's rows and columns brought within a factor of 2 of each other in norm), so every entry of B is an entry of A scaled exactly.

Exceptions
dimension_errorIf a is not square.
non_finite_errorIf an entry is infinite or NaN.

Definition at line 3082 of file eigen.hpp.

◆ matrix_rank()

template<field T>
std::size_t numerical::matrix_rank ( const matrix< T > &  a,
rank_cutoff  cutoff = {},
bool  hermitian = false 
)

The numerical rank of a, as numpy.linalg.matrix_rank counts it: its singular values above cutoff.

Parameters
[in]aThe matrix.
[in]cutoffWhere a singular value counts as zero; by default NumPy's (rank_cutoff).
[in]hermitianWhether a is real symmetric or complex Hermitian, as NumPy's hermitian=True: its singular values are then the magnitudes of its eigenvalues, cheaper to find (in double, real or complex; any other scalar takes its singular values), and only its lower triangle is read.
Exceptions
dimension_errorIf hermitian and a is not square.
non_finite_errorIf an entry read is infinite or NaN.

Definition at line 3215 of file svd.hpp.

◆ max() [1/2]

template<std::totally_ordered T>
T numerical::max ( const tensor< T > &  t)

The largest element (a NaN, if there is one), of a transpose's elements as they lie (in any order the same).

Exceptions
dimension_errorIf t is empty.

Definition at line 3327 of file tensor_ops.hpp.

◆ max() [2/2]

template<std::totally_ordered T>
tensor< T > numerical::max ( const tensor< T > &  t,
std::size_t  axis 
)

The largest elements along axis; a transpose's where its elements lie (detail::as_laid_reduced).

Exceptions
dimension_errorIf axis is not an axis or is empty.

Definition at line 4915 of file tensor_ops.hpp.

◆ max_threads()

std::size_t numerical::max_threads ( )
inlineprivate

The threads a kernel may use: the cap if one is set, else the hardware threads (starting none).

Definition at line 995 of file parallel.hpp.

◆ maximum()

template<std::floating_point T>
tensor< T > numerical::maximum ( const tensor< T > &  a,
const tensor< T > &  b 
)

The larger element of a and b, broadcast, as numpy.maximum (detail::ieee_maximum; a NaN wins, +0 over −0).

The larger element of integer tensors a and b, broadcast, as numpy.maximum.

Exceptions
dimension_errorIf the shapes do not broadcast.

Definition at line 2888 of file tensor_ops.hpp.

◆ mean() [1/2]

template<typename T >
T numerical::mean ( const tensor< T > &  t)

The mean of every element. An empty tensor's mean is NaN, as NumPy's (which also warns).

Definition at line 3301 of file tensor_ops.hpp.

◆ mean() [2/2]

template<typename T >
tensor< T > numerical::mean ( const tensor< T > &  t,
std::size_t  axis 
)

The means along axis; a transpose's where its elements lie (detail::as_laid_reduced).

Exceptions
dimension_errorIf axis is not an axis.

Definition at line 3309 of file tensor_ops.hpp.

◆ min() [1/2]

template<std::totally_ordered T>
T numerical::min ( const tensor< T > &  t)

The smallest element (a NaN, if there is one), of a transpose's elements as they lie (in any order the same).

Exceptions
dimension_errorIf t is empty.

Definition at line 3338 of file tensor_ops.hpp.

◆ min() [2/2]

template<std::totally_ordered T>
tensor< T > numerical::min ( const tensor< T > &  t,
std::size_t  axis 
)

The smallest elements along axis; a transpose's where its elements lie (detail::as_laid_reduced).

Exceptions
dimension_errorIf axis is not an axis or is empty.

Definition at line 4927 of file tensor_ops.hpp.

◆ minimum()

template<std::floating_point T>
tensor< T > numerical::minimum ( const tensor< T > &  a,
const tensor< T > &  b 
)

The smaller element of a and b, broadcast, as numpy.minimum (detail::ieee_minimum; a NaN wins, −0 under +0).

The smaller element of integer tensors a and b, broadcast, as numpy.minimum.

Exceptions
dimension_errorIf the shapes do not broadcast.

Definition at line 2901 of file tensor_ops.hpp.

◆ nonzero()

template<typename T >
std::vector< tensor< std::int64_t > > numerical::nonzero ( const tensor< T > &  t)

The indices of the nonzero elements (x != T {}: a NaN is one), one tensor per axis, in C order, as numpy.nonzero: by chunks on the threads, each chunk's counted, then its indices written at its offset. A chunk walks its elements' indices as an odometer (one division per axis at its start, none after) and writes every element's, the place advancing by one where it is nonzero, without a branch; into a buffer of its own, whose last write may run one past its part.

Definition at line 4442 of file tensor_ops.hpp.

◆ ones()

template<typename T >
tensor< T > numerical::ones ( std::vector< std::size_t >  shape)

A tensor of shape full of ones.

Definition at line 5172 of file tensor_ops.hpp.

◆ operator*() [1/7]

template<typename T >
matrix< T > numerical::operator* ( const matrix< T > &  a,
const matrix< T > &  b 
)

Matrix–matrix product.

Exceptions
dimension_errorIf shapes mismatch.

Definition at line 226 of file matrix.hpp.

◆ operator*() [2/7]

template<typename T >
vector< T > numerical::operator* ( const matrix< T > &  a,
const vector< T > &  v 
)

Matrix–vector product: each element its row's dot product with v (detail::matrix_times_vector).

Exceptions
dimension_errorIf shapes mismatch.

Definition at line 208 of file matrix.hpp.

◆ operator*() [3/7]

template<typename T >
matrix< T > numerical::operator* ( const matrix< T > &  m,
const T &  scalar 
)

Matrix times scalar.

Parameters
[in]m,scalarOperands.
Returns
m·scalar.

Definition at line 199 of file matrix.hpp.

◆ operator*() [4/7]

template<typename T >
matrix< T > numerical::operator* ( const T &  scalar,
const matrix< T > &  m 
)

Scalar times matrix.

Parameters
[in]scalar,mOperands.
Returns
scalar·m.

Definition at line 188 of file matrix.hpp.

◆ operator*() [5/7]

template<typename T >
vector< T > numerical::operator* ( const T &  scalar,
const vector< T > &  v 
)

Scalar times vector.

Parameters
[in]scalar,vOperands.
Returns
scalar·v.

Definition at line 256 of file vector.hpp.

◆ operator*() [6/7]

template<typename T >
tensor< T > numerical::operator* ( const tensor< T > &  a,
const tensor< T > &  b 
)

Element-wise product, broadcast.

Exceptions
dimension_errorIf the shapes do not broadcast.

Definition at line 3043 of file tensor_ops.hpp.

◆ operator*() [7/7]

template<typename T >
vector< T > numerical::operator* ( const vector< T > &  v,
const T &  scalar 
)

Vector times scalar.

Parameters
[in]v,scalarOperands.
Returns
v·scalar.

Definition at line 267 of file vector.hpp.

◆ operator+() [1/3]

template<typename T >
matrix< T > numerical::operator+ ( const matrix< T > &  a,
const matrix< T > &  b 
)

Element-wise sum.

Exceptions
dimension_errorIf the shapes differ.

Definition at line 162 of file matrix.hpp.

◆ operator+() [2/3]

template<typename T >
tensor< T > numerical::operator+ ( const tensor< T > &  a,
const tensor< T > &  b 
)

Element-wise sum, broadcast (a signed integer's wrapped, detail::arithmetic).

Exceptions
dimension_errorIf the shapes do not broadcast.

Definition at line 2822 of file tensor_ops.hpp.

◆ operator+() [3/3]

template<typename T >
vector< T > numerical::operator+ ( const vector< T > &  a,
const vector< T > &  b 
)

Element-wise sum.

Exceptions
dimension_errorIf the sizes differ.

Definition at line 230 of file vector.hpp.

◆ operator-() [1/4]

template<typename T >
matrix< T > numerical::operator- ( const matrix< T > &  a,
const matrix< T > &  b 
)

Element-wise difference.

Exceptions
dimension_errorIf the shapes differ.

Definition at line 175 of file matrix.hpp.

◆ operator-() [2/4]

template<typename T >
tensor< T > numerical::operator- ( const tensor< T > &  a)

Element-wise negation.

Definition at line 3136 of file tensor_ops.hpp.

◆ operator-() [3/4]

template<typename T >
tensor< T > numerical::operator- ( const tensor< T > &  a,
const tensor< T > &  b 
)

Element-wise difference, broadcast.

Exceptions
dimension_errorIf the shapes do not broadcast.

Definition at line 3035 of file tensor_ops.hpp.

◆ operator-() [4/4]

template<typename T >
vector< T > numerical::operator- ( const vector< T > &  a,
const vector< T > &  b 
)

Element-wise difference.

Exceptions
dimension_errorIf the sizes differ.

Definition at line 243 of file vector.hpp.

◆ operator/()

template<typename T >
tensor< T > numerical::operator/ ( const tensor< T > &  a,
const tensor< T > &  b 
)

Element-wise quotient, broadcast.

Exceptions
dimension_errorIf the shapes do not broadcast.

Definition at line 3051 of file tensor_ops.hpp.

◆ partition()

template<typename T >
tensor< T > numerical::partition ( const tensor< T > &  t,
const std::vector< std::size_t > &  kths,
std::size_t  axis 
)

The elements of each line along axis rearranged as numpy.partition: at each of kths the element sort puts there (NaNs last, a complex number by its real part then its imaginary part), none before it that sorts after it, none after it that sorts before; the others in no order specified. By selection, std::nth_element between neighbouring positions, linear in the extent where sort is not.

Exceptions
dimension_errorIf axis is not an axis.
index_errorIf a position is past the extent.

Definition at line 4070 of file tensor_ops.hpp.

◆ pinv()

template<field T>
matrix< T > numerical::pinv ( const matrix< T > &  a,
rank_cutoff  cutoff = {},
bool  hermitian = false 
)

The Moore–Penrose pseudo-inverse of the m × n a (n × m), as numpy.linalg.pinv gives it: V Σ⁺ Uᴴ, a singular value at or under cutoff counting as zero.

Parameters
[in]aThe matrix.
[in]cutoffWhere a singular value counts as zero; by default NumPy's (rank_cutoff).
[in]hermitianWhether a is real symmetric or complex Hermitian, as NumPy's hermitian=True: from its eigendecomposition V Λ Vᴴ, V Λ⁺ Vᴴ, cheaper (in double, real or complex; any other scalar takes its singular value decomposition), and only its lower triangle is read.
Exceptions
dimension_errorIf hermitian and a is not square.
non_finite_errorIf an entry read is infinite or NaN.

Definition at line 3241 of file svd.hpp.

◆ plan_funm()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
funm_plan numerical::plan_funm ( const matrix< T > &  a)

The funm_plan of a: f is then wanted at its points, and finish_funm completes f(A).

Template Parameters
Tdouble or std::complex<double>.
Exceptions
dimension_errorIf a is not square.
non_finite_errorIf an entry is infinite or NaN.
convergence_errorIf the Schur form's iterations did not converge.

Definition at line 2398 of file matrix_functions.hpp.

◆ pow()

template<typename T >
tensor< T > numerical::pow ( const tensor< T > &  a,
const tensor< T > &  b 
)

a to the power b element by element, broadcast, as std::pow; a single exponent of 2, 0.5 or -1 as the library's own x * x, square root (detail::complex_sqrt for a complex one) and 1 / x (exact where pow rounds: a complex square has no stray real part). A complex one keeps C's Annex G, as the operators do: NumPy's loops are detail::numpy_square, detail::numpy_reciprocal and detail::numpy_power.

a to the power b of signed integers element by element, broadcast, as NumPy's: exactly, by repeated squaring, wrapped modulo 2ⁿ.

Exceptions
negative_power_errorIf an exponent is negative (NumPy's refusal: no integer is the answer).
dimension_errorIf the shapes do not broadcast.

Definition at line 3160 of file tensor_ops.hpp.

◆ prod() [1/2]

template<typename T >
T numerical::prod ( const tensor< T > &  t)

The product of every element, in order (numpy.prod's, whose multiplications are sequential: only its sums pair). An empty tensor's is 1.

Definition at line 3351 of file tensor_ops.hpp.

◆ prod() [2/2]

template<typename T >
tensor< T > numerical::prod ( const tensor< T > &  t,
std::size_t  axis 
)

The products along axis, each line in order; a transpose's where its elements lie (detail::as_laid_reduced).

Exceptions
dimension_errorIf axis is not an axis.

Definition at line 3364 of file tensor_ops.hpp.

◆ qr()

template<typename T >
qr_decomposition< T > numerical::qr ( const matrix< T > &  a)

QR-factorises an m × n matrix.

See also
qr_decomposition

Definition at line 3963 of file factorizations.hpp.

◆ qr_r()

template<typename T >
matrix< T > numerical::qr_r ( matrix< T >  a)

The factor R of the QR decomposition of an m × n matrix, k × n, k = min(m, n): qr_decomposition's R to the bit, Q never formed.

Parameters
[in]aThe matrix, any shape, its elements taken over.
Returns
R, upper trapezoidal, its diagonal real and non-negative.
Exceptions
non_finite_errorIf an entry is infinite or NaN.

Definition at line 4300 of file factorizations.hpp.

◆ regathered()

funm_plan numerical::regathered ( funm_plan  plan,
double  share 
)
inline

plan (not Hermitian) with its eigenvalues gathered anew within share of the largest modulus (or of 1): its Schur form reordered by the finer clusters (the same form, their runs moved), its points the eigenvalues, then detail::contour_points on each circle where clusters remain.

Definition at line 2485 of file matrix_functions.hpp.

◆ release_memory()

void numerical::release_memory ( )
inline

Frees the workspaces NumericAL keeps between calls, as oneMKL's mkl_free_buffers: each thread keeps the buffers its kernels last needed (a matrix product's packing, a solve's copies, an eigh's merges, an FFT's scratch), so the next call of a size faults no fresh page in (a solve of order 1000 spent 2.5 ms of its 30 on them), and freed blocks of a few megabytes are kept for the next buffer that fits one. A long-lived process (a server, a notebook) that is done with large problems can give that memory back.

The calling thread's workspaces go at once, and each worker of the thread pool, if it has started, empties its own between two runs, never inside one (this waits for them, at most a second); then the kept blocks go. Another thread's workspaces stay, its own to free by calling this. Last, the allocator is asked to give its free pages back to the system (malloc_trim, malloc_zone_pressure_relief, _heapmin). The next call that needs a workspace makes it anew. Under glibc each thread's arena may keep some freed pages yet (an eight-thread session of order 1500: 210 MB kept, 34 MB after this; with MALLOC_ARENA_MAX=1, 3 MB). Nothing must be running on the calling thread meanwhile, which holds when it calls this between NumericAL's calls.

Definition at line 81 of file memory.hpp.

◆ remainder()

template<typename T >
tensor< T > numerical::remainder ( const tensor< T > &  a,
const tensor< T > &  b 
)

a % b element by element, broadcast, as numpy.remainder (Python's: of b's sign; a real by zero fmod's NaN, detail::floor_divmod).

Exceptions
dimension_errorIf the shapes do not broadcast.

Definition at line 3128 of file tensor_ops.hpp.

◆ reshape()

template<typename T >
tensor< T > numerical::reshape ( const tensor< T > &  t,
std::vector< std::size_t >  shape 
)

The same elements in the same order under another shape, shared with t (no copy).

Exceptions
dimension_errorIf the shapes hold different counts of elements.

Definition at line 4988 of file tensor_ops.hpp.

◆ rfft()

template<std::floating_point T>
tensor< std::complex< T > > numerical::rfft ( const tensor< T > &  a,
std::optional< std::size_t >  n = std::nullopt,
std::ptrdiff_t  axis = -1,
fft_norm  norm = fft_norm::backward 
)

The discrete Fourier transform of real a along axis, its n/2 + 1 non-negative frequencies, as numpy.fft.rfft. An even n by the complex transform of its n/2 pairs and their recombination, an odd one by the complex transform of its points.

Parameters
[in]aA tensor of float or double.
[in]nThe points transformed: the axis cut to them, or padded with zeros; its extent by default.
[in]axisThe axis transformed, negative from the last (the last by default).
[in]normThe scaling (fft_norm): none by default.
Returns
The complex transform, of a's shape with the axis n/2 + 1 long.
Exceptions
dimension_errorIf axis is not an axis of a, or n is 0.

Definition at line 3146 of file fft.hpp.

◆ round() [1/2]

template<detail::split_complex C>
tensor< C > numerical::round ( const tensor< C > &  a,
int  decimals = 0 
)

Every element's real and imaginary parts rounded to decimals places apart, as numpy.round of a complex array.

Definition at line 2983 of file tensor_ops.hpp.

◆ round() [2/2]

template<std::floating_point T>
tensor< T > numerical::round ( const tensor< T > &  a,
int  decimals = 0 
)

Every element rounded to decimals places (tens, hundreds for a negative one), half to even, as numpy.round; a value already exact to those places is kept (detail::decimal_rounding).

Definition at line 2974 of file tensor_ops.hpp.

◆ searchsorted()

template<typename T >
tensor< std::int64_t > numerical::searchsorted ( const tensor< T > &  a,
const tensor< T > &  v,
bool  right = false 
)

Where each element of v would go in the sorted line a to keep it sorted, as numpy.searchsorted: the first such place (right false) or the last, in detail::sorts_before's order (NaNs last).

Exceptions
dimension_errorIf a is not a vector.

Definition at line 4896 of file tensor_ops.hpp.

◆ select_along_last()

template<typename T >
tensor< T > numerical::select_along_last ( const tensor< T > &  t,
const tensor< std::int64_t > &  positions 
)

Of each line along the last axis of t, the elements its stable sort (sort) puts at the positions positions names, as sort(t)[..., positions] reads them, without the sort: each line's positions found by selection (detail::select_row), the lines on the threads. positions has shape (m,), the same for every line, or the lines' shape and m; the result, the lines' shape and m.

Exceptions
dimension_errorIf t has no axis, positions has neither shape, or a position is not in a line.

Definition at line 4786 of file tensor_ops.hpp.

◆ set_max_threads()

void numerical::set_max_threads ( std::size_t  threads)
inlineprivatenoexcept

Caps the threads a kernel uses at threads, the caller's included (1: none beside it, and no thread is started); 0 lifts the cap. For a process that runs several kernels side by side (one per worker process, say), so that together they do not ask for more threads than the machine has.

Definition at line 953 of file parallel.hpp.

◆ sin()

template<typename T >
tensor< T > numerical::sin ( const tensor< T > &  a)

sin of every element: std::sin of a real one (a float the double's, detail::sin_of), detail::complex_sin of a complex one.

Definition at line 2729 of file tensor_ops.hpp.

◆ singular_values()

template<field T>
vector< double > numerical::singular_values ( const matrix< T > &  a)

The singular values of a, descending, without its singular vectors, as numpy.linalg.svd(a, compute_uv=False): the Householder R of a tall A (of Aᴴ when wide), its Golub–Kahan bidiagonal and the dqds algorithm on it (LAPACK's dlasq1, as dgesdd takes it without vectors), no basis formed. Each value to an absolute accuracy of the largest times the machine epsilon, as svd_decomposition's; those of a bidiagonal A each to high relative accuracy.

Exceptions
non_finite_errorIf an entry of a is infinite or NaN.
convergence_errorIf the iteration does not converge within its bound (not observed).

Definition at line 2274 of file svd.hpp.

◆ sinh()

template<std::floating_point T>
tensor< T > numerical::sinh ( const tensor< T > &  a)

sinh of every real element: detail::sinh_into of a double one (within 0.503 ulp of the exact value, finite up to the overflow past 710.47), the double's rounded once of a float one (detail::through_doubles, within half an ulp and 2⁻²⁸).

Definition at line 2684 of file tensor_ops.hpp.

◆ solve() [1/2]

template<field T>
matrix< T > numerical::solve ( matrix< T >  a,
const matrix< T > &  b 
)

Solves A X = B for a square A and every column of B at once, as numpy.linalg.solve with a matrix right-hand side: one factorisation of A, then one substitution per column.

Parameters
[in]aThe square coefficient matrix (n × n).
[in]bThe right-hand sides (n × k).
Returns
X (n × k).
Exceptions
dimension_errorIf a is not square or b's row count differs from it.
singular_matrix_errorIf a is singular.

Definition at line 1805 of file factorizations.hpp.

◆ solve() [2/2]

template<field T>
vector< T > numerical::solve ( matrix< T >  a,
const vector< T > &  b 
)

Solves the linear system A x = b for a square A.

Parameters
[in]aThe square coefficient matrix.
[in]bThe right-hand side.
Returns
The solution x.
Exceptions
dimension_errorIf a is not square or b's size differs from it.
singular_matrix_errorIf a is singular.

Definition at line 1789 of file factorizations.hpp.

◆ solve_banded()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > numerical::solve_banded ( std::size_t  lower,
std::size_t  upper,
const matrix< T > &  ab,
const matrix< T > &  b 
)

The solution X of A X = B for the n × n band A of lower subdiagonals and upper superdiagonals, given as scipy.linalg.solve_banded takes it: ab of lower + upper + 1 rows and n columns, ab[upper + i − j][j] = A(i, j) (its corners, outside the matrix, not read). By the LU factorisation with partial pivoting in LAPACK's band storage (gbsv): O(n · lower · (lower + upper)) operations; one sub- and one superdiagonal by detail::tridiagonal_solve (gtsv), as SciPy.

Template Parameters
Tdouble or std::complex<double>.
Exceptions
dimension_errorIf ab has not lower + upper + 1 rows or b not n rows.
non_finite_errorIf an entry is infinite or NaN.
singular_matrix_errorIf a pivot is zero.

Definition at line 437 of file banded.hpp.

◆ solve_banded_conditioned()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
conditioned_solution< T > numerical::solve_banded_conditioned ( std::size_t  lower,
std::size_t  upper,
const matrix< T > &  ab,
const matrix< T > &  b 
)

solve_banded with the reciprocal condition number of the band, as scipy.linalg.solve takes them from LAPACK's gbsv and gbcon: the band's LU factorisation for any band (gtsv's partial pivoting for three diagonals), ‖A‖₁ its largest column sum of moduli, ‖A⁻¹‖₁ estimated from the factors (Hager's method, a few solves of O(n (lower + upper)) each), so within a small factor of the exact.

Template Parameters
Tdouble or std::complex<double>.
Exceptions
dimension_errorIf ab has not lower + upper + 1 rows or b not n rows.
non_finite_errorIf an entry is infinite or NaN.
singular_matrix_errorIf a pivot is zero.

Definition at line 493 of file banded.hpp.

◆ solve_circulant()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > numerical::solve_circulant ( const vector< T > &  c,
const matrix< T > &  b,
bool  least_squares = false,
std::optional< double >  tol = std::nullopt 
)

The solution X of C X = B for the n × n circulant C of first column c (C(i, j) = c[(i − j) mod n]), as scipy.linalg.solve_circulant: the Fourier transform diagonalises it, X = F⁻¹ (F B / F c), O(n log n) a column. An eigenvalue F c of modulus at most tol (by default n ε max |F c|, as numpy.linalg.matrix_rank judges) makes C near singular: refused, or with least_squares its terms left out (the minimum-norm least-squares solution, SciPy's singular="lstsq"). Real c and b give a real X (the transform's real part, as SciPy's).

Template Parameters
Tdouble or std::complex<double>.
Exceptions
dimension_errorIf b has not n rows.
non_finite_errorIf an entry is infinite or NaN.
singular_matrix_errorIf C is near singular and least_squares is not set.

Definition at line 790 of file banded.hpp.

◆ solve_continuous_are()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > numerical::solve_continuous_are ( const matrix< T > &  a,
const matrix< T > &  b,
const matrix< T > &  q,
const matrix< T > &  r,
const std::type_identity_t< matrix< T > > *  e = nullptr,
const std::type_identity_t< matrix< T > > *  s = nullptr,
bool  balanced = true 
)

The stabilising solution X of the continuous algebraic Riccati equation Aᴴ X E + Eᴴ X A − (Eᴴ X B + S) R⁻¹ (Bᴴ X E + Sᴴ) + Q = 0 (E = I and S = 0 when e and s are null), as scipy.linalg.solve_continuous_are: without e and with R well-conditioned (its condition below 1/√ε), the Schur form of the Hamiltonian [[Ã, −G], [−Q̃, −Ãᴴ]] (Laub, 1979, in real arithmetic for real operands); else, as SciPy, the eigenvalues of the extended Hamiltonian pencil in the left half-plane moved first in its generalized Schur form (generalized_schur), R never inverted. Then one step of Newton's method, kept where it lowers the residual.

Parameters
[in]am × m.
[in]bm × n.
[in]qm × m, Hermitian.
[in]rn × n, Hermitian.
[in]em × m, nonsingular, or null.
[in]sm × n, or null.
[in]balancedWhether the pencil is balanced first (SciPy's default).
Template Parameters
Tdouble or std::complex<double>.
Exceptions
dimension_errorIf an operand's shape differs from those above, or m or n is 0.
non_finite_errorIf an entry is infinite or NaN.
argument_errorIf q or r is not Hermitian.
singular_matrix_errorIf e is numerically singular, or the equation has no finite stabilising solution.
convergence_errorIf the QZ iterations did not converge, or the pencil has eigenvalues too close to the imaginary axis.

Definition at line 3320 of file generalized.hpp.

◆ solve_continuous_lyapunov()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > numerical::solve_continuous_lyapunov ( const matrix< T > &  a,
const matrix< T > &  q 
)

The solution X of the continuous Lyapunov equation A X + X Aᴴ = Q, as scipy.linalg.solve_continuous_lyapunov: one Schur form A = U R Uᴴ, whose adjoint Aᴴ = U Rᴴ Uᴴ it also gives (solve_sylvester with b = Aᴴ formed a second one, twice the time), then R Y + Y Rᴴ = Uᴴ Q U and X = U Y Uᴴ. Rᴴ is lower triangular: with J the order reversed, J Rᴴ J is upper (quasi-)triangular, so R (Y J) + (Y J)(J Rᴴ J) = (Uᴴ Q U) J is solved by blocks as LAPACK's trsyl. Real throughout for real operands, complex where either is.

Template Parameters
Tdouble or std::complex<double>.
Exceptions
dimension_errorIf a is not square or q not of its shape.
non_finite_errorIf an entry is infinite or NaN.
convergence_errorIf the Schur form's iterations did not converge.

Definition at line 915 of file matrix_functions.hpp.

◆ solve_discrete_are()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > numerical::solve_discrete_are ( const matrix< T > &  a,
const matrix< T > &  b,
const matrix< T > &  q,
const matrix< T > &  r,
const std::type_identity_t< matrix< T > > *  e = nullptr,
const std::type_identity_t< matrix< T > > *  s = nullptr,
bool  balanced = true 
)

The stabilising solution X of the discrete algebraic Riccati equation Aᴴ X A − Eᴴ X E − (Aᴴ X B + S) (R + Bᴴ X B)⁻¹ (Bᴴ X A + Sᴴ) + Q = 0 (E = I and S = 0 when e and s are null), as scipy.linalg.solve_discrete_are: the eigenvalues of the extended symplectic pencil inside the unit circle moved first in its generalized Schur form (generalized_schur), nothing inverted.

Parameters
[in]am × m.
[in]bm × n.
[in]qm × m, Hermitian.
[in]rn × n, Hermitian.
[in]em × m, nonsingular, or null.
[in]sm × n, or null.
[in]balancedWhether the pencil is balanced first (SciPy's default).
Template Parameters
Tdouble or std::complex<double>.
Exceptions
dimension_errorIf an operand's shape differs from those above, or m or n is 0.
non_finite_errorIf an entry is infinite or NaN.
argument_errorIf q or r is not Hermitian.
singular_matrix_errorIf e is numerically singular, or the equation has no finite stabilising solution.
convergence_errorIf the QZ iterations did not converge, or the pencil has eigenvalues too close to the unit circle.

Definition at line 3354 of file generalized.hpp.

◆ solve_sylvester()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > numerical::solve_sylvester ( const matrix< T > &  a,
const matrix< T > &  b,
const matrix< T > &  q 
)

The solution X (m × n) of the Sylvester equation A X + X B = Q, as scipy.linalg.solve_sylvester: by Bartels and Stewart's method, the Schur forms A = U R Uᴴ and B = V S Vᴴ (schur_decomposition), R Y + Y S = Uᴴ Q V solved by blocks (LAPACK's trsyl), then X = U Y Vᴴ. Real throughout for real operands (R and S quasi-triangular), complex where any is. Where A and −B share an eigenvalue the equation has no unique solution: a pivot below the rounding of the forms is perturbed, as LAPACK's, and the answer grows accordingly.

Template Parameters
Tdouble or std::complex<double>.
Exceptions
dimension_errorIf a or b is not square or q is not m × n.
non_finite_errorIf an entry is infinite or NaN.
convergence_errorIf a Schur form's iterations did not converge.

Definition at line 876 of file matrix_functions.hpp.

◆ solve_toeplitz()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > numerical::solve_toeplitz ( const vector< T > &  c,
const vector< T > &  r,
const matrix< T > &  b 
)

The solution X of T X = B for the n × n Toeplitz T of first column c and first row r (T(i, j) = c[i − j] for i ≥ j, r[j − i] above; r[0] not read), as scipy.linalg.solve_toeplitz: Levinson's recursion as Numerical Recipes' toeplz (which SciPy's follows), every right-hand side at once, O(n²) operations a column: the solutions of the leading principal systems grown by one row at a time, the forward and backward vectors g and h beside them. It needs every leading principal minor nonsingular (not only T), and like all Levinson recursions it is stable for a well-conditioned symmetric positive definite T and may lose accuracy otherwise.

Template Parameters
Tdouble or std::complex<double>.
Exceptions
dimension_errorIf c and r differ in length or b has not n rows.
non_finite_errorIf an entry is infinite or NaN.
singular_matrix_errorIf a leading principal minor is singular (SciPy's "Singular principal minor").

Definition at line 665 of file banded.hpp.

◆ solve_triangular() [1/2]

template<field T>
vector< T > numerical::solve_triangular ( const matrix< T > &  a,
const vector< T > &  b,
bool  lower,
triangular_op  op = triangular_op::none,
bool  unit_diagonal = false 
)

solve_triangular of one right-hand side.

Definition at line 2376 of file factorizations.hpp.

◆ solve_triangular() [2/2]

template<field T>
matrix< T > numerical::solve_triangular ( const matrix< T > &  a,
matrix< T >  b,
bool  lower,
triangular_op  op = triangular_op::none,
bool  unit_diagonal = false 
)

Solves A X = B, Aᵀ X = B or Aᴴ X = B (op) for a triangular A, as scipy.linalg.solve_triangular: its lower triangle or its upper one is read, the other never, and its diagonal as ones where unit_diagonal. By substitution, a block's rows by rows of terms and the rows past it through the matrix product kernel: n² k multiply-adds, where solve factorises A first.

Parameters
[in]aThe square matrix (n × n).
[in]bThe right-hand sides (n × k).
[in]lowerWhether A is lower triangular, else upper.
[in]opA as it lies, transposed or conjugate-transposed.
[in]unit_diagonalWhether A's diagonal is taken as ones (not read).
Returns
X (n × k).
Exceptions
dimension_errorIf a is not square or b's row count differs from it.
non_finite_errorIf an entry of a's triangle or of b is infinite or NaN.
singular_matrix_errorIf a diagonal entry read is zero (SciPy's message, its 1-based row).

Definition at line 2355 of file factorizations.hpp.

◆ solveh_banded()

template<typename T >
requires std::same_as<T, double> || std::same_as<T, std::complex<double>>
matrix< T > numerical::solveh_banded ( const matrix< T > &  ab,
const matrix< T > &  b,
bool  lower_form = false 
)

The solution X of A X = B for the Hermitian positive-definite band A, given as scipy.linalg.solveh_banded takes it: ab of kd + 1 rows and n columns, its upper form ab[kd + i − j][j] = A(i, j) for i ≤ j or, lower_form, its lower ab[i − j][j] = A(i, j) for i ≥ j (the diagonal's imaginary part, and the corners, not read). By the band's Cholesky factor (LAPACK's pbsv); one off-diagonal by detail::positive_tridiagonal_solve (ptsv), as SciPy.

Template Parameters
Tdouble or std::complex<double>.
Exceptions
dimension_errorIf b has not n rows, or ab has no row.
non_finite_errorIf an entry is infinite or NaN.
not_positive_definite_errorIf A is not positive definite.

Definition at line 563 of file banded.hpp.

◆ sort()

template<typename T >
tensor< T > numerical::sort ( const tensor< T > &  t,
std::size_t  axis 
)

The elements sorted along axis, as numpy.sort: ascending, NaNs last, equal elements in their order (NumPy's kind="stable"; its default sort may order equal ones otherwise, which only a sign of zero shows).

Lines enough for the threads are sorted one to a task; fewer, each is sorted in turn among the threads (detail::parallel_sort_run). A line along the last axis is sorted where it lies in the result.

Exceptions
dimension_errorIf axis is not an axis.

Definition at line 3931 of file tensor_ops.hpp.

◆ sqrt()

template<typename T >
tensor< T > numerical::sqrt ( const tensor< T > &  a)

The square root of every element: std::sqrt of a real one, detail::complex_sqrt of a complex one.

Definition at line 2761 of file tensor_ops.hpp.

◆ sqrtm() [1/2]

matrix< double > numerical::sqrtm ( const matrix< double > &  a)
inline

The real principal square root of a real square matrix, as scipy.linalg.sqrtm answers one: in real arithmetic on its real Schur form (Higham, 1987), a complex pair's block by its own real root.

Exceptions
dimension_errorIf a is not square.
non_finite_errorIf an entry is infinite or NaN.
no_real_root_errorIf a has a real eigenvalue below 0: its principal root is complex (complex_sqrtm).
convergence_errorIf the Schur form's iterations did not converge.

Definition at line 1558 of file matrix_functions.hpp.

◆ sqrtm() [2/2]

matrix< std::complex< double > > numerical::sqrtm ( const matrix< std::complex< double > > &  a)
inline

The principal square root X of a complex square matrix (X² = A, its eigenvalues of nonnegative real part), as scipy.linalg.sqrtm: by the Schur method, A = Z T Zᴴ, the triangular R² = T column by column (Björck and Hammarling), X = Z R Zᴴ. Where A has no square root (a zero eigenvalue in a Jordan block) the entries that would need one are infinite, as SciPy's.

Exceptions
dimension_errorIf a is not square.
non_finite_errorIf an entry is infinite or NaN.
convergence_errorIf the Schur form's iterations did not converge.

Definition at line 1507 of file matrix_functions.hpp.

◆ sum() [1/2]

template<typename T >
T numerical::sum ( const tensor< T > &  t)

The sum of every element, by pairwise halving (0 for an empty tensor), on the threads where they are many (detail::parallel_pairwise_sum): the same bits.

The sum of every element of a signed integer tensor, wrapped modulo 2ⁿ as NumPy's (in any order the same bits: the unsigned sum is associative, so a transpose's elements are summed as they lie), by chunks on the threads where they are many.

Definition at line 3229 of file tensor_ops.hpp.

◆ sum() [2/2]

template<typename T >
tensor< T > numerical::sum ( const tensor< T > &  t,
std::size_t  axis 
)

The sums along axis, by pairwise halving; a transpose's where its elements lie (detail::as_laid_reduced; each line's sum the same).

The sums along axis of a signed integer tensor, wrapped modulo 2ⁿ as NumPy's; a transpose's where its elements lie (detail::as_laid_reduced).

Exceptions
dimension_errorIf axis is not an axis.

Definition at line 3237 of file tensor_ops.hpp.

◆ swapped()

constexpr fft_norm numerical::swapped ( fft_norm  norm)
constexprnoexcept

norm with its forward and backward exchanged, as NumPy's hfft and ihfft take it.

Definition at line 3175 of file fft.hpp.

◆ symmetric_eigenvalues()

template<field T>
vector< double > numerical::symmetric_eigenvalues ( const matrix< T > &  a)

The eigenvalues of the real symmetric or complex Hermitian a, ascending, without its eigenvectors, as numpy.linalg.eigvalsh: its Householder tridiagonal (no basis formed) and the implicit QL iteration on it, no rotation kept. Only the lower triangle is read, and of the diagonal its real part. Each value to an absolute accuracy of the largest magnitude times the machine epsilon, as symmetric_eigen's; a graded tridiagonal's small values to their relative accuracy, as LAPACK's dsteqr keeps them.

Exceptions
dimension_errorIf a is not square.
non_finite_errorIf an entry read is infinite or NaN.
convergence_errorIf the iteration does not converge within its bound (not observed).

Definition at line 2328 of file svd.hpp.

◆ take()

template<typename T >
tensor< T > numerical::take ( const tensor< T > &  t,
const tensor< std::int64_t > &  indices,
std::size_t  axis,
take_mode  mode 
)

The elements of t at indices along axis, as numpy.take: the result's shape t's with the axis replaced by indices' shape. Under take_mode::raise a negative index counts from the axis's end; under wrap an index is taken modulo the extent; under clip, at the nearer end. Each index read once, then the elements copied on the threads.

Exceptions
index_errorUnder take_mode::raise, for the first index outside the axis, in NumPy's words, unless the axes before axis hold no element (NumPy then checks none); under any mode, from an empty axis where the result has elements, or under wrap with any index.
dimension_errorIf axis is not an axis, or the result's elements overflow.

Definition at line 4593 of file tensor_ops.hpp.

◆ take_along_axis()

template<typename T >
tensor< T > numerical::take_along_axis ( const tensor< T > &  t,
const tensor< std::int64_t > &  indices,
std::size_t  axis 
)

The elements of t at indices along axis, the other axes matched, as numpy.take_along_axis: indices of t's rank and shape but along the axis (any extent there), each in [0, extent); read directly, on the threads.

Exceptions
dimension_errorIf the shapes do not match so, or an index is out of its range.

Definition at line 4542 of file tensor_ops.hpp.

◆ tan()

template<typename T >
tensor< T > numerical::tan ( const tensor< T > &  a)

tan of every element: std::tan of a real one, detail::complex_tan of a complex one.

Definition at line 2744 of file tensor_ops.hpp.

◆ tanh()

template<typename T >
tensor< T > numerical::tanh ( const tensor< T > &  a)

tanh of every element: detail::tanh_into of a double one (within 0.502 ulp of the exact value), the double's rounded once of a float one (detail::through_doubles, within half an ulp and 2⁻²⁸), detail::complex_tanh of a complex one.

Definition at line 2754 of file tensor_ops.hpp.

◆ toeplitz()

template<typename T >
matrix< T > numerical::toeplitz ( const vector< T > &  c,
const vector< T > &  r 
)

The m × n Toeplitz matrix of first column c (m entries) and first row r (n), as scipy.linalg.toeplitz: T(i, j) = c[i − j] for i ≥ j, r[j − i] above (r[0] not read).

Definition at line 844 of file banded.hpp.

◆ transpose()

template<typename T >
matrix< T > numerical::transpose ( const matrix< T > &  m)

The transpose, by blocks of transpose_tile (walked by detail::transpose_piece's pieces), the result's blocks of rows shared among the threads.

Parameters
[in]mThe matrix.
Returns
An cols×rows matrix.

Definition at line 251 of file matrix.hpp.

◆ triangle()

template<typename T >
tensor< T > numerical::triangle ( const tensor< T > &  t,
std::ptrdiff_t  k,
bool  lower 
)

The matrices of t (its last two axes) zero above their k diagonal (lower) or below it (else), as numpy.tril and numpy.triu: each row's kept part copied and the rest zeroed, by rows on the threads.

Exceptions
dimension_errorIf t has fewer than two axes.

Definition at line 5048 of file tensor_ops.hpp.

◆ triangle_indices()

std::array< tensor< std::int64_t >, 2 > numerical::triangle_indices ( std::size_t  rows,
std::size_t  cols,
std::ptrdiff_t  k,
bool  lower 
)
inline

The row and the column indices of the rows × cols matrix's part to and below its k diagonal (lower) or to and above it (else), in row-major order, as numpy.tril_indices and numpy.triu_indices: each row's count, their offsets, then the rows written on the threads.

Definition at line 5091 of file tensor_ops.hpp.

◆ triangular_reciprocal_condition()

template<field T>
double numerical::triangular_reciprocal_condition ( const matrix< T > &  a,
bool  lower 
)

The reciprocal condition number 1 / (‖A‖₁ ‖A⁻¹‖₁) of a triangular matrix, as LAPACK's trcon (1-norm): its lower triangle or its upper one read, the other never; ‖A⁻¹‖₁ estimated by substitutions (Hager's method), so within a small factor of the exact.

Parameters
[in]aThe square matrix.
[in]lowerWhether A is lower triangular, else upper.
Returns
The estimate: 1 for an empty matrix; 0 for a zero on the diagonal or an estimate that overflows.
Exceptions
dimension_errorIf a is not square.
non_finite_errorIf an entry of its triangle is infinite or NaN.

Definition at line 2327 of file factorizations.hpp.

◆ tridiagonal_eigen()

std::pair< vector< double >, matrix< double > > numerical::tridiagonal_eigen ( const vector< double > &  d,
const vector< double > &  e 
)
inline

The eigenvalues, ascending, and the orthonormal eigenvectors (the columns, in their order) of the real symmetric tridiagonal matrix of diagonal d and off-diagonal e, as scipy.linalg.eigh_tridiagonal: divide and conquer (LAPACK's dstedc, the eigenvectors by matrix products), the implicit QL iteration up to its leaves' order, on the matrix divided by the power of two of its largest magnitude.

Exceptions
dimension_errorIf e has not one entry fewer than d (none for an empty d).
non_finite_errorIf an entry is infinite or NaN.
convergence_errorIf an iteration does not converge within its bound (not observed).

Definition at line 2862 of file svd.hpp.

◆ tridiagonal_eigenvalue_range()

std::pair< std::ptrdiff_t, std::ptrdiff_t > numerical::tridiagonal_eigenvalue_range ( const vector< double > &  d,
const vector< double > &  e,
double  low,
double  high 
)
inline

The indices [first, last] (ascending, from 0) of the eigenvalues in (low, high] of the real symmetric tridiagonal matrix of diagonal d and off-diagonal e, by Sturm's counts (last < first where none lies there), as dstebz selects them with a range.

Exceptions
dimension_errorIf e has not one entry fewer than d.
non_finite_errorIf an entry is infinite or NaN.

Definition at line 2516 of file svd.hpp.

◆ tridiagonal_eigenvalues() [1/2]

vector< double > numerical::tridiagonal_eigenvalues ( const vector< double > &  d,
const vector< double > &  e 
)
inline

The eigenvalues of the real symmetric tridiagonal matrix of diagonal d and off-diagonal e, ascending, as scipy.linalg.eigvalsh_tridiagonal: the implicit QL iteration, no rotation kept, on the matrix divided by the power of two of its largest magnitude (as symmetric_eigenvalues runs it on the tridiagonal it forms).

Exceptions
dimension_errorIf e has not one entry fewer than d (none for an empty d).
non_finite_errorIf an entry is infinite or NaN.
convergence_errorIf the iteration does not converge within its bound (not observed).

Definition at line 2405 of file svd.hpp.

◆ tridiagonal_eigenvalues() [2/2]

vector< double > numerical::tridiagonal_eigenvalues ( const vector< double > &  d,
const vector< double > &  e,
std::size_t  first,
std::size_t  last 
)
inline

The eigenvalues of indices first to last (ascending, from 0) of the real symmetric tridiagonal matrix of diagonal d and off-diagonal e, as LAPACK's dstebz (scipy.linalg.eigvalsh_tridiagonal with a selection): each by bisection of Gershgorin's interval on Sturm's counts, to ε ‖T‖ (LAPACK's tolerance when none is given), on the matrix divided by the power of two of its largest magnitude. n k operations a bisection step where the QL iteration takes n² for all.

Exceptions
dimension_errorIf e has not one entry fewer than d, or first > last or last ≥ n.
non_finite_errorIf an entry is infinite or NaN.

Definition at line 2459 of file svd.hpp.

◆ tridiagonal_eigenvectors()

matrix< double > numerical::tridiagonal_eigenvectors ( const vector< double > &  d,
const vector< double > &  e,
const vector< double > &  values 
)
inline

The orthonormal eigenvectors (the columns, in their order) of the real symmetric tridiagonal matrix of diagonal d and off-diagonal e for the eigenvalues values, ascending (from tridiagonal_eigenvalues with indices, say), as LAPACK's dstein: inverse iteration (detail::inverse_iteration), some n operations a solve for each, where all the eigenvectors take n³; on the matrix divided by the power of two of its largest magnitude. Where an iterate does not converge or a cluster is too large, the vectors are the whole spectrum's (tridiagonal_eigen) of the eigenvalues nearest.

Exceptions
dimension_errorIf e has not one entry fewer than d, or values are not ascending.
non_finite_errorIf an entry is infinite or NaN.

Definition at line 2800 of file svd.hpp.

◆ vdot()

template<typename T >
T numerical::vdot ( const tensor< T > &  a,
const tensor< T > &  b 
)

Σ conj(a[i]) · b[i] over every element of a and b in their row-major order, as numpy.vdot: the plain sum of products for reals, the conjugated one for complex numbers without a conjugated copy of a (detail::chunked_conjugate_dot, BLAS's zdotc), both by chunks among the threads, the same on any number of them.

Exceptions
dimension_errorIf the two hold different counts of elements.

Definition at line 4157 of file tensor_ops.hpp.

◆ zeros()

template<typename T >
tensor< T > numerical::zeros ( std::vector< std::size_t >  shape)

A tensor of shape full of zeros (each thread's share zeroed as the C library zeroes).

Definition at line 5132 of file tensor_ops.hpp.

Variable Documentation

◆ hermitian_expm_least

constexpr std::size_t numerical::hermitian_expm_least {64}
inlineconstexpr

The order from which expm of a Hermitian matrix takes its eigendecomposition (below, the Padé path is faster: an order-32 symmetric_eigen costs more than the few products of a small Padé degree).

Definition at line 380 of file matrix_functions.hpp.

◆ sliced_copy_most

constexpr std::size_t numerical::sliced_copy_most {512}
inlineconstexpr

The most elements tensor::sliced copies at once rather than viewing (4 KiB of doubles).

Definition at line 76 of file tensor.hpp.

◆ transpose_tile

constexpr std::size_t numerical::transpose_tile {32}
inlineconstexpr

The square blocks transpose copies one at a time: a block's rows of the source and of the result both stay in the L1 cache, where a row of the result walked a column of the source a stride apart.

Definition at line 243 of file matrix.hpp.