feat: initial release

Assisted-by: GLM 5.3 Flash

CHANGELOG.md

@@ -0,0 +1,348 @@
+# 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.