tensor/integrate/ode.go

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

package integrate

import (
	"sourcedock.dev/petrbalvin/tensor/internal/base"
	"sourcedock.dev/petrbalvin/tensor/internal/core"
)

import (
	"errors"
	"math"
)

// Ordinary differential equation solvers for initial value problems
// y' = f(t, y). The state y is a rank-1 vector of length n; a system
// of higher rank flattens to its leading-axis vector first.
//
// Three schemes cover the standard regimes. IntegrateODE is the
// workhorse: an adaptive embedded Runge-Kutta pair (Dormand-Prince
// 4(5)) that controls the local error against a mixed absolute and
// relative tolerance. IntegrateRK4 is the classical fixed-step
// fourth-order scheme, useful when a uniform step or simple
// reproducibility per step matters. IntegrateBackwardEuler is the
// entry-level stiff scheme: fully implicit, with each step's
// nonlinear equation solved by Newton over a numerical Jacobian and
// the library's LU solver.

// ODEOptions tunes the adaptive integrator. RelTol ≤ 0 means 1e-6,
// AbsTol ≤ 0 means 1e-9, MaxSteps ≤ 0 means 100000.
type ODEOptions struct {
	RelTol   float64
	AbsTol   float64
	MaxSteps int
}

// Dormand-Prince 4(5): node offsets, stage coefficients, and the
// 5th- and 4th-order solution weights. Stage 7 shares the 5th-order
// weights (the FSAL property), which is why it needs no separate row.
var (
	odeC = [7]float64{0, 1.0 / 5, 3.0 / 10, 4.0 / 5, 8.0 / 9, 1, 1}
	odeA = [][]float64{
		{},
		{1.0 / 5},
		{3.0 / 40, 9.0 / 40},
		{44.0 / 45, -56.0 / 15, 32.0 / 9},
		{19372.0 / 6561, -25360.0 / 2187, 64448.0 / 6561, -212.0 / 729},
		{9017.0 / 3168, -355.0 / 33, 46732.0 / 5247, 49.0 / 176, -5103.0 / 18656},
		{35.0 / 384, 0, 500.0 / 1113, 125.0 / 192, -2187.0 / 6784, 11.0 / 84},
	}
	odeB5 = [7]float64{35.0 / 384, 0, 500.0 / 1113, 125.0 / 192, -2187.0 / 6784, 11.0 / 84, 0}
	odeB4 = [7]float64{5179.0 / 57600, 0, 7571.0 / 16695, 393.0 / 640, -92097.0 / 339200, 187.0 / 2100, 1.0 / 40}
)

// IntegrateODE integrates y' = f(t, y) from t0 to t1 with the adaptive
// Dormand-Prince 4(5) pair and returns y(t1). Backward integration
// works: a t1 < t0 simply integrates in the negative direction. An
// exhausted step budget, a collapsed step size or an f that returns a
// wrongly shaped state is an error, never a silently truncated
// trajectory.
func IntegrateODE(f func(t float64, y *core.Array) (*core.Array, error),
	t0, t1 float64, y0 *core.Array, opts ODEOptions) (*core.Array, error) {
	return odeRun(f, t0, t1, y0, opts, nil)
}

// readVector copies a's elements into dst, sweeping the raw float64
// payload when a is a dense float64 array and falling back to the
// widening accessor for views and other dtypes. The values written are
// identical either way.
func readVector(dst []float64, a *core.Array) {
	if !a.Strided() && a.Dtype() == core.Float {
		copy(dst, a.RawFloats())
		return
	}
	for i := range dst {
		dst[i] = a.FloatAt(i)
	}
}

// denseFloats returns a's elements as a plain float64 slice, sharing
// the payload when a is a dense float64 array and copying the widened
// values otherwise. The values read are the ones the accessor
// returned; a shared slice is read-only, and only an array the caller
// owns may be written through it. A caller sweeping the elements of a
// solver's result uses this instead of one accessor call per element.
func denseFloats(a *core.Array) []float64 {
	if !a.Strided() && a.Dtype() == core.Float {
		return a.RawFloats()
	}
	out := make([]float64, a.Len())
	for i := range out {
		out[i] = a.FloatAt(i)
	}
	return out
}

// odeRun drives the adaptive Dormand-Prince loop over the whole span.
// When watch is not nil it is called after every accepted step with
// the interval just integrated and clones of the states at both ends;
// a true return stops the integration there, and the watch's error
// aborts it. Everything else behaves exactly like IntegrateODE.
func odeRun(f func(t float64, y *core.Array) (*core.Array, error),
	t0, t1 float64, y0 *core.Array, opts ODEOptions,
	watch func(tPrev, tNow float64, yPrev, yNow []float64) (bool, error)) (*core.Array, error) {
	const name = "IntegrateODE"
	y, err := odeCheck(name, y0, &opts)
	if err != nil {
		return nil, err
	}
	n := len(y)
	w := &odeWork{}
	w.useStage(n)
	k := make([][]float64, 8) // k[1..7] are the stages; k[0] unused
	for i := 1; i <= 7; i++ {
		k[i] = make([]float64, n)
	}
	// One scratch accumulator serves every stage of every step: it is
	// rebuilt from y at the top of each stage call and read only by
	// that call's f evaluation, the same transient view the package's
	// fixed-step solvers hand out.
	acc := w.stage
	stage := func(i int, t float64, h float64) error {
		copy(acc, y)
		row := odeA[i-1]
		for j := 1; j < i; j++ {
			if row[j-1] == 0 {
				continue
			}
			// The step-scaled weight is one product, the same (h·a)·k
			// grouping the plain component loop evaluated.
			hj := h * row[j-1]
			kj := k[j]
			for m := range n {
				acc[m] += hj * kj[m]
			}
		}
		out, err := odeCall(name, f, t+odeC[i-1]*h, acc, n, &w.views)
		if err != nil {
			return err
		}
		readVector(k[i], out)
		return nil
	}

	t := t0
	h := odeInitialStep(t0, t1, y)
	budget := odeBudget{max: opts.MaxSteps}
	yEnd := w.yEnd
	// The solution weights scaled by the step size: one product each,
	// the same (h·b)·k grouping the component loop evaluated.
	var hb5, hb4 [7]float64
	for !odeArrived(t, t1) {
		if err := budget.spend(name, t, t1); err != nil {
			return nil, err
		}
		// Never step past t1; t1−t carries the integration direction.
		h = odeClampStep(h, t, t1)
		for j := 1; j <= 7; j++ {
			hb5[j-1] = h * odeB5[j-1]
			hb4[j-1] = h * odeB4[j-1]
		}
		for i := 1; i <= 7; i++ {
			if err := stage(i, t, h); err != nil {
				return nil, err
			}
		}
		// The embedded pair: the 5th-order solution advances, the gap
		// to the 4th-order one estimates the local error.
		errNorm := 0.0
		for m := range n {
			y5, y4 := y[m], y[m]
			for j := 1; j <= 7; j++ {
				y5 += hb5[j-1] * k[j][m]
				y4 += hb4[j-1] * k[j][m]
			}
			yEnd[m] = y5
			scale := opts.AbsTol + opts.RelTol*math.Max(math.Abs(y[m]), math.Abs(y5))
			ratio := (y5 - y4) / scale
			errNorm += ratio * ratio
		}
		errNorm = math.Sqrt(errNorm/float64(n)) + 1e-10

		factor := math.Min(5, math.Max(0.2, 0.9*math.Pow(1/errNorm, 1.0/5)))
		if errNorm <= 1 {
			if watch != nil {
				stop, werr := watch(t, t+h, cloneDenseSlice(y), cloneDenseSlice(yEnd))
				if werr != nil {
					return nil, werr
				}
				if stop {
					return arrayFromVector(yEnd), nil
				}
			}
			copy(y, yEnd)
			prevT := t
			t += h
			h *= factor
			// Collapse is "t did not move", not "h is small": a span
			// far below the absolute time scale is perfectly
			// integrable, and the old absolute floor refused it.
			if t == prevT {
				return nil, base.Errf("%s: the step size shrank below the resolution of t at t=%g", name, prevT)
			}
		} else {
			// Rejected: retry the same interval with the smaller step.
			h *= math.Max(0.2, factor)
		}
	}
	return arrayFromVector(y), nil
}

// IntegrateODEPath integrates y' = f(t, y) from t0 to t1 and returns
// the trajectory sampled at nSamples evenly spaced points, endpoints
// included: times[i] is the sample time and states[i] the state there,
// so states[0] is the initial state and states[nSamples−1] the answer
// IntegrateODE would return. Every interval between neighbouring
// samples is integrated on its own, so the adaptive step control never
// has to align with the sampling grid. Backward integration
// (t1 < t0) works, and the error contract of IntegrateODE applies
// per interval.
func IntegrateODEPath(f func(t float64, y *core.Array) (*core.Array, error),
	t0, t1 float64, y0 *core.Array, nSamples int, opts ODEOptions) ([]float64, []*core.Array, error) {
	if nSamples < 2 {
		return nil, nil, base.Errf("IntegrateODEPath: nSamples must be ≥ 2, got %d", nSamples)
	}
	y, err := odeCheck("IntegrateODEPath", y0, &opts)
	if err != nil {
		return nil, nil, base.Errf("IntegrateODEPath: %w", err)
	}
	times := make([]float64, nSamples)
	states := make([]*core.Array, nSamples)
	times[0] = t0
	states[0] = wrapVector(y)
	// The last sample is pinned to t1 exactly; the intermediate ones
	// are the evenly spaced grid.
	for i := 1; i < nSamples; i++ {
		times[i] = t0 + float64(i)*(t1-t0)/float64(nSamples-1)
	}
	times[nSamples-1] = t1
	for i := 1; i < nSamples; i++ {
		states[i], err = IntegrateODE(f, times[i-1], times[i], states[i-1], opts)
		if err != nil {
			return nil, nil, base.Errf("IntegrateODEPath: %w", err)
		}
	}
	return times, states, nil
}

// IntegrateODESteps integrates y' = f(t, y) from t0 to t1 and returns
// the trajectory as recorded at every accepted solver step: times[i]
// carries states[i] = y(times[i]), starting with (t0, y0) and ending
// with (t1, y(t1)). The accepted steps are where the adaptive control
// judged the local error within tolerance, so they are the natural
// interpolation nodes for post-processing, sensitivity analysis and
// adjoint passes. Backward integration records descending times; the
// error contract of IntegrateODE applies.
func IntegrateODESteps(f func(t float64, y *core.Array) (*core.Array, error),
	t0, t1 float64, y0 *core.Array, opts ODEOptions) ([]float64, []*core.Array, error) {
	y, err := odeCheck("IntegrateODESteps", y0, &opts)
	if err != nil {
		return nil, nil, base.Errf("IntegrateODESteps: %w", err)
	}
	times := []float64{t0}
	states := []*core.Array{wrapVector(y)}
	watch := func(tPrev, tNow float64, yPrev, yNow []float64) (bool, error) {
		times = append(times, tNow)
		// yNow is the run's own per-call clone; nothing aliases it.
		states = append(states, wrapVector(yNow))
		return false, nil
	}
	if _, err := odeRun(f, t0, t1, y0, opts, watch); err != nil {
		return nil, nil, base.Errf("IntegrateODESteps: %w", err)
	}
	// The run's last accepted boundary is t+h with h = t1−t, which
	// rounds a few ulps off t1 whenever the magnitudes demand it; the
	// documented endpoint is t1 exactly, and the recorded state there
	// is already the run's answer y(t1).
	times[len(times)-1] = t1
	return times, states, nil
}

// IntegrateRK4 integrates y' = f(t, y) with the classical fixed-step
// fourth-order Runge-Kutta scheme over the given number of equal
// steps, returning y(t1).
func IntegrateRK4(f func(t float64, y *core.Array) (*core.Array, error),
	t0, t1 float64, y0 *core.Array, steps int) (*core.Array, error) {
	if steps <= 0 {
		return nil, base.Errf("IntegrateRK4: steps must be ≥ 1, got %d", steps)
	}
	y, err := odeCheck("IntegrateRK4", y0, nil)
	if err != nil {
		return nil, err
	}
	n := len(y)
	h := (t1 - t0) / float64(steps)
	k1 := make([]float64, n)
	k2 := make([]float64, n)
	k3 := make([]float64, n)
	k4 := make([]float64, n)
	tmp := make([]float64, n)
	views := &odeViews{}
	call := func(t float64, v []float64, out []float64) error {
		o, err := odeCall("IntegrateRK4", f, t, v, n, views)
		if err != nil {
			return err
		}
		readVector(out, o)
		// A non-finite stage flows straight into the state with no
		// rejection mechanism to catch it, and the fixed-step run
		// would publish NaN with a nil error; the adaptive drivers
		// reject it, this one has to refuse it.
		for i := range n {
			if math.IsNaN(out[i]) || math.IsInf(out[i], 0) {
				return base.Errf("IntegrateRK4: f returned the non-finite value %g at coordinate %d, t=%g", out[i], i, t)
			}
		}
		return nil
	}
	// The stage times come from the exact grid t0 + i·h, never from an
	// accumulated t += h: the addition's rounding walks over a long run
	// (measured on y' = cos t from t0 = 1e6 the walk contributes an
	// error of 1.1e-8 that no step count refines away), while each grid
	// point carries a single rounding that stays put.
	for i := range steps {
		t := t0 + float64(i)*h
		if err := call(t, y, k1); err != nil {
			return nil, err
		}
		for i := range n {
			tmp[i] = y[i] + h*k1[i]/2
		}
		if err := call(t+h/2, tmp, k2); err != nil {
			return nil, err
		}
		for i := range n {
			tmp[i] = y[i] + h*k2[i]/2
		}
		if err := call(t+h/2, tmp, k3); err != nil {
			return nil, err
		}
		for i := range n {
			tmp[i] = y[i] + h*k3[i]
		}
		if err := call(t+h, tmp, k4); err != nil {
			return nil, err
		}
		for i := range n {
			y[i] += h * (k1[i] + 2*k2[i] + 2*k3[i] + k4[i]) / 6
		}
	}
	return arrayFromVector(y), nil
}

// IntegrateBackwardEuler integrates y' = f(t, y) with the fully
// implicit Euler scheme y_{n+1} = y_n + h·f(t_{n+1}, y_{n+1}), solving
// each step by Newton over a numerical Jacobian and the library's LU
// solver. The extra work per step is what buys stability on stiff
// systems, where the explicit schemes need step sizes far below what
// accuracy alone would ask for.
func IntegrateBackwardEuler(f func(t float64, y *core.Array) (*core.Array, error),
	t0, t1 float64, y0 *core.Array, steps int, opts ODEOptions) (*core.Array, error) {
	if steps <= 0 {
		return nil, base.Errf("IntegrateBackwardEuler: steps must be ≥ 1, got %d", steps)
	}
	y, err := odeCheck("IntegrateBackwardEuler", y0, &opts)
	if err != nil {
		return nil, err
	}
	n := len(y)
	h := (t1 - t0) / float64(steps)
	yn := cloneDenseSlice(y)
	seed := make([]float64, n)
	fy := make([]float64, n)
	// One Newton result buffer serves every step: it aliases neither the
	// state nor the seed, and each step overwrites it fully.
	zbuf := make([]float64, n)
	w := &odeWork{}
	// The step times come from the exact grid t0 + i·h, never from an
	// accumulated t += h: the addition's rounding walks over a long
	// run, while each grid point carries a single rounding that stays
	// put.
	for i := range steps {
		tNext := t0 + float64(i+1)*h
		// Newton on G(z) = z − y_n − h·f(t_{n+1}, z) = 0, seeded with
		// the semi-implicit Euler prediction.
		out, ferr := odeCall("IntegrateBackwardEuler", f, tNext, yn, n, &w.views)
		if ferr != nil {
			return nil, ferr
		}
		readVector(fy, out)
		for i := range n {
			seed[i] = yn[i] + h*fy[i]
		}
		if nerr := odeNewton("IntegrateBackwardEuler", f, w, tNext, 1, h, yn, seed,
			zbuf, opts.AbsTol, opts.RelTol); nerr != nil {
			return nil, nerr
		}
		copy(yn, zbuf)
	}
	return arrayFromVector(yn), nil
}

// errNewtonStalled marks an implicit solve whose Newton iteration ran
// out of budget or hit a singular matrix without converging. A driver
// that can shrink the step retries on it; a failed f evaluation is a
// different, fatal error.
var errNewtonStalled = errors.New("the Newton iteration did not converge")

// odeCall evaluates f at (t, v) and validates that the result is a
// vector of the expected length n, returning it unchanged. views,
// when not nil, caches the read-only wrapper handed to f, which a
// driver calling f repeatedly wants; a cold call site passes nil.
// Callers that need plain floats follow up with odeEval; callers that
// want to place the values themselves read them straight off the
// array.
func odeCall(name string, f func(t float64, y *core.Array) (*core.Array, error),
	t float64, v []float64, n int, views *odeViews) (*core.Array, error) {
	out, err := f(t, views.of(v))
	if err != nil {
		return nil, base.Errf("%s: %w", name, err)
	}
	if out.NDim() != 1 || out.Len() != n {
		return nil, base.Errf("%s: f returned shape %s, want a vector of length %d",
			name, base.ShapeText(out.Shape()), n)
	}
	return out, nil
}

// odeEval calls f at (t, v) and returns the derivative as a plain
// float64 slice.
func odeEval(name string, f func(t float64, y *core.Array) (*core.Array, error),
	t float64, v []float64, n int, views *odeViews) ([]float64, error) {
	out, err := odeCall(name, f, t, v, n, views)
	if err != nil {
		return nil, err
	}
	r := make([]float64, n)
	readVector(r, out)
	return r, nil
}

// odeBudget counts attempted solver steps against the MaxSteps option:
// the budget is spent before the step's stages are evaluated, so a
// rejected step consumes it like an accepted one.
type odeBudget struct {
	used int
	max  int
}

// spend spends one step of the budget, failing once it is exhausted.
func (b *odeBudget) spend(name string, t, t1 float64) error {
	if b.used >= b.max {
		return base.Errf("%s: reached MaxSteps=%d at t=%g before t1=%g", name, b.max, t, t1)
	}
	b.used++
	return nil
}

// odeClampStep caps h so a step never overshoots t1; t1−t carries the
// integration direction.
func odeClampStep(h, t, t1 float64) float64 {
	if math.Abs(h) > math.Abs(t1-t) {
		return t1 - t
	}
	return h
}

// odeArrived reports whether t sits within a few ulps of t1. The
// accumulating t += h can miss the exact endpoint by rounding once
// t and t1 differ in magnitude beyond Sterbenz territory, and the
// residual distance is indistinguishable from zero at working
// precision, so the solvers treat it as arrived rather than report a
// collapsed step over it.
func odeArrived(t, t1 float64) bool {
	if t == t1 {
		return true
	}
	return math.Abs(t1-t) <= 8*base.EpsF*math.Max(math.Abs(t), math.Abs(t1))
}

// odeWork holds the scratch the implicit schemes reuse across the
// steps of one run: the Newton vectors, one flat numerical Jacobian
// with its difference stencils, the factored matrix's rows, the ROS4
// stage buffers and the read-only views handed to f. Every buffer is
// overwritten before it is read, so a run builds the workspace once
// and no step allocates scratch of its own.
type odeWork struct {
	// The Newton iteration's residual, step and derivative buffers,
	// plus the DAE mass-matrix product M·z.
	g, col, fzs []float64
	mz          []float64
	// jac is the numerical Jacobian as one flat n×n buffer, row-major:
	// jac[i*n+j] is ∂f_i/∂z_j.
	jac []float64
	// The Jacobian's central-difference stencils: the two perturbed
	// states and their two results.
	zp, zm, fp, fm []float64
	// mat is the implicit relation's matrix in row-major rows, ROS4's
	// (1/(γh))I − J or Newton's α·I − h·J depending on the caller, with
	// perm the row permutation its factorisation produced. Factor
	// shuffles the rows in place, and every rebuild rewrites the lot.
	mat  [][]float64
	perm []int
	// The ROS4 stage buffers: the four divided differences, the stage
	// value, its right side, f's result and the candidate end state.
	ks             [4][]float64
	stage, rhs, fy []float64
	yEnd           []float64
	// The Newton iterate the implicit schemes iterate in, and the visit
	// bitmap the stage permutation walks: both reused across every step
	// and every attempt of one run.
	zwork   []float64
	visited []bool
	// views caches the wrapper handed to f per scratch slice.
	views odeViews
}

// use returns the workspace's buffers at the state length n, growing
// them on first use. The content is left as the previous step wrote
// it: every consumer overwrites its buffer before reading it.
func (w *odeWork) use(n int) {
	w.g = sizedBuf(w.g, n)
	w.col = sizedBuf(w.col, n)
	w.fzs = sizedBuf(w.fzs, n)
	w.mz = sizedBuf(w.mz, n)
	w.jac = sizedBuf(w.jac, n*n)
	w.zp = sizedBuf(w.zp, n)
	w.zm = sizedBuf(w.zm, n)
	w.fp = sizedBuf(w.fp, n)
	w.fm = sizedBuf(w.fm, n)
	w.mat = sizedRows(w.mat, n)
	for s := range w.ks {
		w.ks[s] = sizedBuf(w.ks[s], n)
	}
	w.stage = sizedBuf(w.stage, n)
	w.rhs = sizedBuf(w.rhs, n)
	w.fy = sizedBuf(w.fy, n)
	w.yEnd = sizedBuf(w.yEnd, n)
	w.zwork = sizedBuf(w.zwork, n)
	w.visited = sizedBools(w.visited, n)
}

// useStage returns the explicit step loop's buffers at the state
// length n, growing them on first use: the stage accumulator and the
// candidate end state are all an explicit pair needs, and sizing the
// implicit buffers here would allocate the Jacobian and the factored
// matrix for a loop that never takes a derivative.
func (w *odeWork) useStage(n int) {
	w.stage = sizedBuf(w.stage, n)
	w.yEnd = sizedBuf(w.yEnd, n)
}

// sizedBuf returns b cut to length n, reusing its storage when it is
// large enough.
func sizedBuf(b []float64, n int) []float64 {
	if cap(b) < n {
		return make([]float64, n)
	}
	return b[:n]
}

// sizedBools returns b cut to length n, reusing its storage when it is
// large enough.
func sizedBools(b []bool, n int) []bool {
	if cap(b) < n {
		return make([]bool, n)
	}
	return b[:n]
}

// odePermuteColumn reorders col in place so that col[i] takes the
// value that sat at perm[i], the permutation the workspace's LU
// factorisation produced. The walk carries each displaced value around
// its cycle exactly as the library's PermuteColumn does, plain
// assignments moving each value once, so the column ends up bit-
// identical; the difference is that the visit bitmap is the caller's
// reused scratch rather than a fresh allocation per call. The bitmap
// is cleared on entry, so a dirty buffer behaves exactly like a fresh
// one.
func odePermuteColumn(col []float64, perm []int, visited []bool) {
	vis := visited[:len(col)]
	clear(vis)
	for i := range col {
		if vis[i] || perm[i] == i {
			vis[i] = true
			continue
		}
		// Carry the displaced value around the cycle.
		tmp := col[i]
		j := i
		for {
			vis[j] = true
			k := perm[j]
			if k == i {
				break
			}
			col[j] = col[k]
			j = k
		}
		col[j] = tmp
	}
}

// arrayFromVector copies a float64 slice into a fresh rank-1 float64
// array: the trajectory endpoint contract, without the intermediate
// wrapper a cloneArray(wrapVector(...)) pair built. The result never
// aliases the input.
func arrayFromVector(v []float64) *core.Array {
	a := core.New(core.Float, len(v))
	copy(a.RawFloats(), v)
	return a
}

// sizedRows returns m as n row slices of length n, reusing the rows it
// already holds. The rows' content is the caller's to overwrite.
func sizedRows(m [][]float64, n int) [][]float64 {
	if cap(m) < n {
		m = make([][]float64, n)
	}
	m = m[:n]
	for i := range m {
		m[i] = sizedBuf(m[i], n)
	}
	return m
}

// odeViews caches the read-only wrapper handed to f for one scratch
// slice, so a driver that calls f thousands of times builds the
// wrapper once per slice instead of once per call. The values behind
// the wrapper are the driver's own scratch and keep changing exactly
// as they did; only the Array header is reused. The slices a driver
// hands in are few, so a linear scan beats a map; a driver that
// presents a fresh slice every call cannot grow the cache without
// bound, because the oldest entry makes way.
type odeViews struct {
	entries []odeView
}

type odeView struct {
	vals []float64
	arr  *core.Array
}

// odeViewSlots bounds the cache. A driver holds a handful of scratch
// slices at once, and each slot pins one sliced buffer, so the bound
// keeps both the scan and the retention small.
const odeViewSlots = 8

// of returns a read-only view of s, reusing the one already built for
// that slice. A nil cache builds a fresh view, which is what a cold
// call site wants.
func (v *odeViews) of(s []float64) *core.Array {
	if v == nil || len(s) == 0 {
		return wrapVector(s)
	}
	for i := range v.entries {
		e := &v.entries[i]
		if len(e.vals) == len(s) && &e.vals[0] == &s[0] {
			return e.arr
		}
	}
	arr := wrapVector(s)
	if len(v.entries) == odeViewSlots {
		copy(v.entries, v.entries[1:])
		v.entries = v.entries[:odeViewSlots-1]
	}
	v.entries = append(v.entries, odeView{vals: s, arr: arr})
	return arr
}

// odeJacobian fills the workspace's flat Jacobian with the central
// differences of f at (t, z), one column per state component:
// entry i*n+j is ∂f_i/∂z_j. The returned slice is the workspace's, so
// it stays valid until the next Jacobian. The two perturbed stencils
// and their two result buffers are reused across columns: each round
// rebuilds the stencils from z and overwrites both results before
// reading them.
func odeJacobian(name string, f func(t float64, y *core.Array) (*core.Array, error),
	t float64, z []float64, w *odeWork) ([]float64, error) {
	n := len(z)
	w.use(n)
	jac := w.jac
	for j := range n {
		eps := math.Sqrt(base.EpsF) * math.Max(1, math.Abs(z[j]))
		copy(w.zp, z)
		copy(w.zm, z)
		w.zp[j] += eps
		w.zm[j] -= eps
		out, e1 := odeCall(name, f, t, w.zp, n, &w.views)
		if e1 != nil {
			return nil, e1
		}
		readVector(w.fp, out)
		out, e2 := odeCall(name, f, t, w.zm, n, &w.views)
		if e2 != nil {
			return nil, e2
		}
		readVector(w.fm, out)
		for i := range n {
			jac[i*n+j] = (w.fp[i] - w.fm[i]) / (2 * eps)
		}
	}
	return jac, nil
}

// odeNewton solves the implicit step equation α·z − h·f(tNext, z) = β
// for z by Newton over a numerical Jacobian and the library's LU
// solver, writing the converged state into dst and returning an error
// otherwise. The Jacobian is frozen from the seed and rebuilt twice
// when convergence drags, so a converged step costs one Jacobian and a
// handful of f evaluations. The iteration runs in the workspace's own
// buffer and the column permutation walks the workspace's bitmap, so
// the only allocation a converged step costs is the caller's dst: a
// driver whose dst recycles through a ring allocates its result
// buffers once per solve, not once per step, and a rejected or stalled
// attempt allocates nothing. dst must not alias seed or beta; the
// workspace overwrites it fully at convergence. Convergence is
// measured on the residual against the error scale the caller
// integrates to, an order of magnitude below it, but never below the
// floating-point floor of the residual's own terms, which would
// otherwise be unreachable at the tiny steps a stiff start begins
// with. An iteration that outlives twenty rounds, or a singular Newton
// matrix, surfaces as errNewtonStalled so a stepping driver can retry
// with a smaller step; an f that fails is the fatal error it is.
func odeNewton(name string, f func(t float64, y *core.Array) (*core.Array, error),
	w *odeWork, tNext float64, alpha, h float64, beta, seed, dst []float64,
	absTol, relTol float64) error {
	n := len(seed)
	w.use(n)
	// The iterate starts as the seed and stays the workspace's buffer:
	// the views cache then hands f one stable wrapper for every Newton
	// call of the run.
	z := sizedBuf(w.zwork, n)
	copy(z, seed)
	for iteration := range 20 {
		out, err := odeCall(name, f, tNext, z, n, &w.views)
		if err != nil {
			return err
		}
		readVector(w.fzs, out)
		worst, terms := 0.0, 0.0
		for i := range n {
			w.g[i] = alpha*z[i] - h*w.fzs[i] - beta[i]
			worst = math.Max(worst, math.Abs(w.g[i]))
			terms = math.Max(terms, math.Abs(alpha*z[i])+math.Abs(h*w.fzs[i])+math.Abs(beta[i]))
		}
		limit := math.Max(0.1*(absTol+relTol*normInfOfStep(z)), 8*base.EpsF*terms)
		if worst <= limit {
			copy(dst, z)
			return nil
		}
		if iteration == 0 || iteration == 4 || iteration == 10 {
			jac, jerr := odeJacobian(name, f, tNext, z, w)
			if jerr != nil {
				return jerr
			}
			// Newton matrix α·I − h·J, a fresh LU for the frozen
			// Jacobian; the iterations that follow only substitute.
			// Every row is rebuilt entry by entry before the
			// factorisation reads it.
			for i := range n {
				row := w.mat[i]
				for j := range n {
					row[j] = -h * jac[i*n+j]
				}
				row[i] += alpha
			}
			w.perm, _ = base.Factor(w.mat)
			if err := base.CheckSingular(name, w.mat); err != nil {
				return base.Errf("%s: %w, singular Newton matrix at t=%g",
					name, errNewtonStalled, tNext)
			}
		}
		for i := range n {
			w.col[i] = -w.g[i]
		}
		odePermuteColumn(w.col, w.perm, w.visited)
		base.SolveColumn(w.mat, w.col)
		for i := range n {
			z[i] += w.col[i]
		}
	}
	return base.Errf("%s: %w at t=%g", name, errNewtonStalled, tNext)
}

// odeCheck validates the initial state, applies option defaults and
// returns the flat float64 working state.
func odeCheck(name string, y0 *core.Array, opts *ODEOptions) ([]float64, error) {
	if y0.NDim() != 1 {
		return nil, base.Errf("%s: the state must be a vector, got shape %s", name, base.ShapeText(y0.Shape()))
	}
	if y0.Len() == 0 {
		return nil, base.Errf("%s: the state must not be empty", name)
	}
	if y0.Dtype() == core.Complex {
		return nil, base.Errf("%s: complex states are not supported", name)
	}
	if opts != nil {
		if opts.RelTol <= 0 {
			opts.RelTol = 1e-6
		}
		if opts.AbsTol <= 0 {
			opts.AbsTol = 1e-9
		}
		if opts.MaxSteps <= 0 {
			opts.MaxSteps = 100000
		}
	}
	return cloneDense(y0), nil
}

// odeInitialStep guesses the first step size as a small fraction of
// the integration span, carrying the direction in its sign.
func odeInitialStep(t0, t1 float64, y []float64) float64 {
	h := 0.01 * math.Abs(t1-t0)
	if h == 0 {
		h = 1e-6
	}
	// The step sign carries the integration direction: a t1 < t0
	// integrates backwards.
	if t1 < t0 {
		h = -h
	}
	return h
}

// cloneArray copies an array element by element, so the integration
// steps' results never alias a buffer already handed out.
func cloneArray(a *core.Array) *core.Array {
	out := core.New(a.Dtype(), a.Shape()...)
	switch a.Dtype() {
	case core.Float:
		copy(out.RawFloats(), a.RawFloats())
	case core.Float32:
		copy(out.RawFloat32s(), a.RawFloat32s())
	case core.Int:
		copy(out.RawInts(), a.RawInts())
	default:
		copy(out.RawComplexes(), a.RawComplexes())
	}
	return out
}

// normInfOfStep returns the infinity norm of a step vector.
func normInfOfStep(step []float64) float64 {
	worst := 0.0
	for _, v := range step {
		if a := math.Abs(v); a > worst {
			worst = a
		}
	}
	return worst
}

// wrapVector views a float64 slice as a rank-1 Array without copying.
// The caller must treat the result as read-only.
func wrapVector(v []float64) *core.Array {
	a, _ := core.FloatsFromArray(v, len(v))
	return a
}

// cloneDense copies an array's elements into a plain float64 slice,
// widening int and float32 elements exactly.
func cloneDense(y0 *core.Array) []float64 {
	vals := make([]float64, y0.Len())
	for i := range vals {
		vals[i] = y0.FloatAt(i)
	}
	return vals
}

// cloneDenseSlice copies a float64 slice.
func cloneDenseSlice(v []float64) []float64 {
	out := make([]float64, len(v))
	copy(out, v)
	return out
}