tensor/CHANGELOG.md

# Changelog

All notable changes to **Tensor** are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.0.0] - 2026-09-03

The initial release of Tensor, a scientific computing library in pure
Go: immutable n-dimensional arrays over a wide element-type set,
dense and sparse linear algebra, differential equations, quadrature,
signal transforms, statistics up to mixed models and hidden Markov
models, optimisation from simplex to stochastic global search, a
reverse-mode differentiable core, deterministic SVG plotting and an
experimental SPMD package, with no third-party dependencies and a
deterministic, parallel execution model.

The module is one core package plus one package per domain:
`sourcedock.dev/petrbalvin/tensor` carries the `Array` core with
element-wise math, special functions and the reproducible generator,
re-exporting the whole surface of every domain package; `linalg` the
dense and sparse solvers; `signal` the transforms, filters and
stencils; `integrate` the differential equations and quadrature;
`stats` the distributions and inference; `optim` the fitting and root
finding; `io` the CSV, FITS, HDF5, NetCDF and memory-mapped readers
and writers; `grad` the differentiable core; `plot` the deterministic
figures. Import what you use: the domain packages depend on the core,
never on each other except through five one-directional edges, and
nothing below the root imports the root. The experimental `spmd`
package stands beside them, imported explicitly: a distributed
program names it, the facade does not.

### Added

**Core arrays.**

- Immutable, shape-checked n-dimensional arrays over int64, float32,
  float64, complex128, IEEE 754 float16 and the narrow integer types
  Int8, Uint8, Int16, Uint16, Int32 and Uint32, with Bool beside
  them, under a strict promotion ladder, row-major layout and
  multi-rank text formatting. Constructors cover literals
  (`FromInts`, `FromFloat32s`, `FromFloats`, `FromComplexes`,
  `FromFloat16s`, `FromInt8s` and the family around them), filled and
  ranged builders (`Zeros`, `Ones`, `FullI`/`FullF`/`FullC`, `Range`,
  `RangeBy`, `Linspace`, `Grid`), byte loading and dtype conversions
  (`WithInt`/`WithFloat`/`WithComplex`, and `Astype`, which
  range-checks every conversion into a narrow target with an error
  naming the value and its index).
- Element-wise arithmetic with scalar variants, transcendentals,
  comparisons that answer a bool mask of one byte per element
  composing through `And`, `Or`, `Xor` and `Not` (`Where` and
  `Select` keep the int mask), and reductions from `Sum`, `Mean`,
  `Min`/`Max`, `Prod` and `Dot` through axis variants, `ArgMax`,
  `TopK`, `CumSum` and `CumProd` to `SumKahan` compensated summation.
  Every float fold cuts its line through a canonical partition fixed
  by the length alone and combines the partials through a balanced
  tree, so a reduction's answer is a function of the data alone,
  never of the machine, and `CumSum` carries a Neumaier compensation
  term so a long prefix sheds no small addend.
- Shape operations (`Reshape`, `Flatten`, `Squeeze`, `Transpose`,
  `TransposeAxes`, `MoveAxis`, `Pad`, `Tile`, `Repeat`, `Flip`, `Roll`,
  `Diag`, triangular extractions), indexing (contiguous `Slice`
  selections as read-only payload views, `Gather`, `Scatter`, `Take`,
  `Nonzero`, `Argwhere`, `SearchSorted`), and the toolkit pieces
  `Einsum`, `Unique`, `OneHot`, `CrossProduct`, `Sort`, `ArgSort`,
  and the numeric `Jacobian` of a vector function by central
  differences.
- `MatMul2D`, the parallel cache-friendly kernel; sparse matrices as
  `SparseCOO`; interpolation (`Interpolate`, the Fritsch-Carlson
  `InterpolateMonotone`, `Interpolate2D`, `InterpolateGrid`, natural
  cubic splines); and special functions: the gamma and beta families,
  error functions, Bessel of integer order and, through
  `BesselJRealOrder`, of any real order, Airy and Fresnel families,
  exponential integrals, orthogonal polynomials, spherical harmonics,
  elliptic integrals and Jacobi functions, and `Cosm1` for
  `cos(x) − 1` at the arguments where the direct subtraction has no
  correct significant bit.
- Quasirandom sequences for Monte Carlo integration: `HaltonPoints`
  and the base-2 digital `SobolPoints` (Joe and Kuo initialisation,
  40 dimensions).
- Parallel execution across every core with a fixed reduction order,
  `SetNumCPU` to pin the worker count, and pooled scratch buffers
  whose borrow path zeroes the window.
- The reproducible `Generator`: xoshiro256++ seeded through
  splitmix64, stable across Go releases, with uniform, normal and
  truncated-normal draws, shuffles and permutations; `Splitmix64` and
  `Substream` are exported for callers who seed their own streams.
  The distribution draws of the `stats` package take the same
  generator, so a seeded program replays exactly.

**Linear algebra.**

- Dense factorisations and solves: LU (`Solve`, `Inv`, `Det`), QR
  beside `RRQR`, the rank-revealing column-pivoted factorisation with
  `RRQRRank` and `SolveRRQR`, whose rank-deficient path answers the
  minimum-norm solution, Cholesky with rank-one update and downdate,
  `LeastSquares`, the tridiagonal and cyclic-tridiagonal solvers,
  `Pinverse`, `MatrixRank`, `Cond`.
- Eigenproblems in the symmetric, Hermitian-complex, general and
  generalised forms; `SVD` and `SVDComplex` in real and complex
  arithmetic; `SchurComplex`; the matrix functions `MatrixExp`,
  `MatrixSqrt` and `MatrixLog`.
- Regularised and truncated solves for ill-posed systems:
  `SolveTruncated` (rank truncation of the singular spectrum) and
  `SolveTikhonov` (Tikhonov damping through the SVD).
- Sparse direct factorisations: `CSCFromCOO` and the `SparseCSC` view
  with `ToCSR`/`ToCSC` conversions, `NewSparseCholesky`, the sparse
  Cholesky with the elimination tree, the natural, reverse
  Cuthill-McKee and minimum-degree orderings and the rank-one
  `Update` and `Downdate`, and `NewSparseLU`, the Gilbert-Peierls
  left-looking elimination with partial pivoting. One factorisation
  solves any number of right-hand sides.
- Sparse iterative methods on the CSR view: `SpSolve` (conjugate
  gradient), `SpSolveBiCGSTAB`, `SpLSQR` and `SpLSMR` for
  overdetermined systems, the ILU(0) preconditioner, the Lanczos
  eigensolver `SpEigen` with its general Arnoldi form, and
  `SpExpApply`, the Krylov action of a matrix exponential. The
  complex side mirrors it for Hermitian positive-definite and general
  non-Hermitian operators, the shape Helmholtz and electromagnetics
  problems need.
- Polynomial fitting, roots through the companion matrix, and the
  fluent `Pipeline` chain over the element-wise surface.

**Signal and transforms.**

- Fourier transforms of any length: `FFT`/`IFFT`, `FFT2`, `FFT3`,
  `FFTN`/`IFFTN`, the real-input `RFFT`/`IRFFT` pair and `FFTFreq`.
- Cosine and sine transforms (orthonormal types I to IV), the
  type-1 non-uniform FFT by Gaussian gridding, and the short-time
  Fourier transform with window choice.
- Spectral estimation: `WelchPSD`, `Spectrogram`, `LombScargle` for
  unevenly sampled data, and the spectral Poisson solves in periodic,
  Dirichlet and Neumann boundaries.
- Sample-rate conversion: `Decimate` behind a Kaiser anti-alias
  filter, rational `Resample` and exact band-limited
  `ResampleFourier`; the Hilbert `AnalyticSignal` and `Envelope`; and
  `Chirp`, the linear frequency sweep synthesised from the
  closed-form phase at each sample.
- Filter design: Butterworth, Chebyshev, inverse Chebyshev and
  elliptic (Cauer) responses in low-pass, high-pass, band-pass and
  band-stop forms with explicit ripple and attenuation budgets,
  applied through `FilterApply` and, zero phase, through `Filtfilt`.
- Correlation and wavelets: FFT-based `Autocorrelate` and
  `CrossCorrelate`, `PartialAutocorrelate`, the Haar `DWT`/`IDWT` and
  the Daubechies families db2 to db8, and the analytic `CWT` (Morlet
  and Mexican hat).
- Convolutions, pooling and windows: `Conv1D`/`Conv2D`/`Conv3D` with
  groups and dilation, `ConvTranspose2D`, the max, average, adaptive
  and global pooling families, the `MedianFilter` and `RankFilter`
  families in one and two dimensions, the `SavitzkyGolay` smoother,
  the `Gradient1D`/`Laplacian` stencils, and the public window
  catalogue `WindowHann` through `WindowBox`, each in the symmetric
  and the periodic convention.
- Time-series estimation: `KalmanFilter`, `ExtendedKalmanFilter` and
  `UnscentedKalmanFilter` with the filtered states, covariance
  history, innovations and the summed log likelihood;
  `EstimateAR` through Yule-Walker over the Levinson recursion,
  `EstimateARMA` through Hannan-Rissanen innovations, `SelectARMA`
  over a lag grid by information criterion, and `ARMASpectrum` for
  the theoretical one-sided spectrum.

**Differential equations and quadrature.**

- Initial value problems: `IntegrateODE` (adaptive Dormand-Prince
  4(5)) with path and step recording, `IntegrateBDF2` and
  `IntegrateBDFVar` (variable order 1 to 5, VODE-style step and order
  adaptation) for stiff systems, `IntegrateROS4`, the L-stable
  Rosenbrock-Wanner solver, `IntegrateBackwardEuler`, `IntegrateRK4`,
  event detection with direction filters, `IntegrateDAE` for
  semi-explicit index-1 differential-algebraic systems in mass-matrix
  form, and the symplectic `IntegrateVerlet` beside `IntegrateYoshida4`
  and `IntegrateMidpoint` for separable and general Hamiltonians.
- Boundary values: `IntegrateBoundary` by damped shooting with the
  root finder of `optim`, and `SolveBoundaryCollocation` by
  three-point Lobatto IIIA collocation on an adaptively refined mesh.
- Quadrature: adaptive Gauss-Legendre `IntegrateFunction`, fixed-node
  `GaussLegendreNodes`, `IntegrateND`, globally adaptive cubature
  over hyperrectangles, and `IntegrateFilon` for the oscillatory
  integrals of a smooth amplitude against a cosine or sine carrier.
- Turnkey PDE evolution: the heat equation by Crank-Nicolson in one
  dimension and Peaceman-Rachford ADI in two, the wave equation by
  velocity Verlet in one dimension and an explicit central stencil in
  two, advection by the monotone upwind and Koren-limited fluxes and
  their advection-diffusion combination, CFL enforced everywhere.
- Finite elements: structured and arbitrary triangular meshes in two
  dimensions and tetrahedral meshes in three, with
  `SolvePoissonFEM2D` and `SolvePoissonFEM3D`, the piecewise-linear
  Poisson assemblies through the sparse direct factorisation, with
  Dirichlet lifting and natural Neumann boundaries.

**Statistics.**

- Distributions: CDFs, quantiles and matched random draws for the
  normal, exponential, gamma, chi-square, Student t, F and their
  noncentral forms, Poisson, binomial, negative binomial, Weibull,
  lognormal, Pareto and Dirichlet laws, built on the incomplete gamma
  and beta functions.
- Descriptives: mean-free moments, `Median`, `Quantile`, histograms
  in one and two dimensions, the robust `MedianAbsoluteDeviation` and
  `TrimmedMean`, and the rolling windows.
- Inference: `WelchTTest`, `KolmogorovSmirnovTest`, `MannWhitneyU`,
  one-way `ANOVAOneWay`, `ChiSquareGoodnessOfFit`, `BootstrapCI`, the
  rank correlations `SpearmanRho` and `KendallTau`, the
  multiple-testing corrections `Bonferroni`, `Holm` and
  `BenjaminiHochberg`, and the contingency table analyses
  `FisherExactTest`, `ChiSquareIndependence`, `McNemarTest` and
  `CramersV`.
- Models: `LinearRegression` with standard errors, t-tests, p-values,
  R² and the model F-test, `WeightedLinearRegression`,
  `LogisticRegression` and `PoissonRegression` on the exact
  likelihood with Wald inference, `HuberRegression`,
  `TheilSenRegression` and `QuantileRegression` for the robust and
  distribution-free fits, lasso and elastic net over a documented
  regularisation path, `PCA`, `KMeans` with k-means++ seeding,
  `GaussianMixture` selected over a component grid by
  `GaussianMixtureBIC`, Gaussian-process regression over
  squared-exponential, Matern 3/2 and 5/2 and periodic kernels,
  multivariate normal densities and draws, Gaussian `KernelDensity`,
  `LinearMixedModel`, the Gaussian linear mixed model with grouped
  random effects estimated by residual maximum likelihood, the
  discrete hidden Markov model with its `Forward`, `Smooth` and
  `Viterbi` recursions and its Baum-Welch fit, and
  `HierarchicalClustering`, the agglomerative dendrogram with the
  single, complete, average, centroid and Ward linkages and the
  `Dendrogram` cuts into flat clusters.

**Optimisation.**

- Local: `Minimise` (Nelder-Mead simplex), `MinimiseLBFGS` with box
  bounds and a projected-gradient convergence measure, and
  `LevenbergMarquardt` with an optional analytic Jacobian. The
  `LevenbergMarquardtFit` form reports χ², a named `FitStatus` and,
  on request, the parameter covariance and per-residual weights
  through `Sigma`, and the least squares and system solvers take
  `ParallelJacobian`, an explicit opt-in that spreads the
  finite-difference columns across workers with bit-identical
  answers.
- Constrained: `MinimiseConstrained`, the augmented Lagrangian over
  the box, so equality and inequality rows of `LinearConstraints`
  compose with the walls, and `MinimiseNonlinearConstrained` for rows
  that are arbitrary functions.
- Global: `MinimiseDifferentialEvolution` for multimodal,
  derivative-free landscapes, `MinimiseCMAES` (the rank-one and
  rank-mu update set, seeded through the generator) and
  `MinimiseSimulatedAnnealing` (geometric cooling), all deterministic
  under a seed and all honest about an exhausted budget.
- Programming: `MinimiseLinear` and `MinimiseLinearRows`, the revised
  simplex with a two-phase start over standard-form and two-sided row
  programs, and `MinimiseQP`, the active-set method for the strictly
  convex program with the multipliers returned.
- Root finding: `FindRoot` (Brent), `FindRootBrent` for a scalar
  bracketed root, `FindRootNewton` and `FindRootSystem` (damped
  Newton with Armijo backtracking and an optional Broyden rank-one
  update in place of repeated Jacobian builds). A solver that
  exhausts its budget is refused with an error unless the
  best-effort exit is requested by name.

**Automatic differentiation.**

- A reverse-mode graph over the arithmetic surface, the matrix
  products (single and batched), the reductions, slicing,
  concatenation, axis permutation and the Fourier transforms; every
  float leaf accumulates through `Backward`.
- Complex tensors differentiate under the Wirtinger convention, the
  loss stays real, and mixed real-complex graphs compose exactly
  through the 2·Re narrowing.
- Second order: `Hessian` (forward-over-reverse) and
  `HessianVectorProduct` in two gradient evaluations.
- On top of the graph: `MinimiseNewtonCG` (truncated-CG Newton with
  an Armijo line search), `SampleHMC` (Hamiltonian Monte Carlo on any
  differentiable unnormalised density) and `AdjointODE` (adjoint
  sensitivities at the cost of one extra solve).

**Plotting.**

- The `plot` package: deterministic SVG line charts of computed
  series. Linear axes with five ticks, one legend line per series, a
  `Line` constructor straight from two rank-1 arrays through the
  promotion ladder, and a byte-identical file on every run, so a
  figure in a paper is compared exactly like any other computed
  number.

**Distributed execution.**

- The experimental `spmd` package: explicit SPMD worlds, one program
  on many ranks, over TCP between machines or in one process over
  channels, launched, listened for and joined through `Launch`,
  `Listen` and `Join`. The movement collectives `Broadcast`,
  `Scatter`, `Gather` and `AllGather` move arrays between ranks; the
  sharded reductions cut a global array on the canonical fold
  partition's block boundaries and combine the partials through the
  same balanced tree the single-array fold uses, so `Sum`, `Min`,
  `Max`, `Any`, `All`, `Prod`, the norm and the dot families answer
  the single-array reduction's exact bits at any world size, whatever
  the order the frames arrive in; `Reduce` and `AllReduce` fold the
  ranks' same-shaped arrays elementwise in rank index order.
  `ExchangeHalos` and `ExchangeHalosOnGrid` hand each rank's boundary
  slabs to the neighbours of a decomposition laid out on a row-major
  process grid. Every failure or deadline fails the whole world
  loudly, and no collective ever returns a partial numeric result.

**Data I/O.**

- CSV reading and writing, with or without a header row, every stored
  numeric dtype written and read.
- FITS images with header cards in both directions, and binary and
  ASCII table extensions.
- HDF5 in both directions: `LoadHDF5` reads the default and the
  "latest" file formats (contiguous, compact and chunked storage, the
  deflate, shuffle and fletcher32 filters, superblocks of versions 2
  and 3 with the lookup3 checksum of each verified, group attributes
  merged into each dataset), and `SaveHDF5` with `SaveHDF5Text`
  writes every stored dtype at its native width, booleans through the
  HDF5 enumeration convention, nested groups, attributes and optional
  filters, byte-deterministic on every run. Unsupported format
  features are refused by name, and cyclic or over-deep group walks
  are refused.
- `LoadNetCDF`/`SaveNetCDF` for the NetCDF classic model (CDF-1 and
  CDF-2), with named dimensions, text attributes and record
  dimensions in both directions, and fixed-point variables landing at
  their own width and sign.
- Memory mapping: `MapFloats`, `MapFloat32s` and `MapInts` open
  native-endian files as read-only arrays without reading them, and
  `SaveNativeFloats` writes the format they read.

**Examples.**

- Thirteen runnable workflows in `examples/`: ODE parameter fitting
  by adjoint sensitivities, PSF deconvolution, HMC sampling, spectral
  analysis, wavelet denoising, the exact pendulum period through
  `EllipticK`, a Helmholtz system on the complex sparse solvers,
  quasi-Monte Carlo integration, heat and wave evolution, regression
  inference, a FITS star field, a NetCDF climate round trip and an
  FFT tour.

**Project.**

- A determinism oracle pinning fixed workloads through the facade by
  SHA-256 digest of the output bits, and a resource-leak harness
  holding the goroutine count and live heap to baseline under
  repeated heavy runs.
- Gitea Actions pipelines for test, race and release, with the
  release notes extracted from this file's matching section.
- The document set: this changelog, the README, the API reference,
  the architecture, the development guide, the benchmarking method,
  the contribution rules and the security policy, under the MIT
  licence.