// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
// SPDX-License-Identifier: MIT

// Package tensor is the public facade of the library: every exported
// symbol of every domain package is re-exported here under one name,
// so user code imports only "sourcedock.dev/petrbalvin/tensor" and
// writes tensor.Everything. The implementations live in the domain
// packages (linalg, signal, integrate, stats, optim, io, grad) and the
// shared array core in internal/core.
//
// # What it is
//
// A scientific computing library in pure Go: no cgo, no GPU stack, no
// third-party dependencies. Arrays over int64, float32, float64 and
// complex128 with a strict promotion ladder and loud shape errors;
// dense and sparse linear algebra through eigensolvers, decompositions
// and Krylov methods; Fourier, cosine/sine, wavelet and continuous
// wavelet transforms; ordinary differential equations with events and
// adjoint sensitivities; PDE evolution in one and two space dimensions;
// quadrature and cubature; distributions, inference and linear
// regression with classical errors; global and local optimisation; and
// a reverse-mode differentiable core that covers the arithmetic, the
// transforms and the second-order questions alike.
//
// # A tour in one breath
//
//	z, _ := tensor.MatMul2D(a, b)              // dense linear algebra
//	spec, _ := tensor.FFT(x)                   // transforms, any length
//	end, _ := tensor.IntegrateODE(f, 0, 1, y0, tensor.ODEOptions{})
//	res, _ := tensor.LinearRegression(X, y)    // full inference
//	loss.Backward()                            // exact gradients
//	xs, _ := tensor.MinimiseNewtonCG(f, x0, tensor.NewtonCGOptions{})
//
// The examples in this documentation are executable and checked by
// the test suite; the examples/ directory carries the longer
// workflows (ODE parameter fitting, PSF deconvolution, HMC sampling,
// spectral analysis).
//
// # The guarantees
//
//   - Deterministic: parallel kernels reduce in a fixed order, so a
//     given element order gives bit-identical results run to run;
//     SetNumCPU pins the parallelism.
//   - Loud: a shape mismatch, a singular matrix, an exhausted solver
//     budget or a CFL violation is an error naming itself, never a
//     silently wrong number.
//   - Immutable: operations never modify their inputs.
//   - Reproducible: the generator is xoshiro256++ seeded through
//     splitmix64, stable across Go releases, and Substream hands out
//     the provably distinct members of one seed's stream family.
//
// # Conventions
//
// Functions return (value, error) and wrap errors with context;
// scalars come back as Scalar when the dtype follows the input. The
// names are the library's own: consistent with the established
// patterns here rather than borrowed from any other array library.
package tensor