Classes
class	AndersonOracle

class	MarchResult

Functions
	run_map (solver)

	jacobi_eigh (A, tol=1e-15, max_sweeps=50)

	scaled_eig (RR)

	cond_scaled (lam)

	solve_truncated (D, lam, V, b)

	pinv_truncated (XX)

	gelfand_radius (T)

	march_to_steady (solver, monitor, *rtol=1e-4, max_steps=5000, accelerate=True, window=5, check_every=5, num_passes=3, slow_rate=0.997, roundoff=1e-11, callback=None, oracle_kw=None, holder=None, budget=None, rev=1)

	settings_of (name)

	build_solver (flow, scheme, N, sdf_fn, L, *rho, mu, F, dt, advection, settings, vel_sweeps=200)

	main ()

Variables
int	K_MAX_WINDOW = 8

int	K_ENGAGE_DECREASES = 2

float	K_RESTART_GROWTH = 4.0

int	K_MAX_RESTARTS = 5

int	K_NOISE_FLOOR = 1e-10

int	K_COND_MIN = 1e-12

int	K_RITZ_DELTA = 1e-3

int	K_RITZ_HI = 1e-2

int	K_RITZ_CONSECUTIVE = 3

int	K_GELFAND_SQUARINGS = 20

float	K_RITZ_FLOOR_FACTOR = 1000.0

	VELOCITY

	PRESSURE

	CARRIED

dict	MAP_STATS = {"calls": 0, "seconds": 0.0, "pressure_iterations": 0}

float	L1 = 1.0

list	ZH_PHI = [0.000125, 0.001, 0.008, 0.027, 0.064, 0.125, 0.216, 0.343, 0.45, 0.5236]

list	ZH_K = [1.096, 1.212, 1.525, 2.008, 2.810, 4.292, 7.442, 15.4, 28.1, 42.1]

Detailed Description

Python oracle for Anderson acceleration of steady marches (doc/steady_acceleration.md, WO-1).

An INSTRUMENT, not a gate and not production code. It implements the design note exactly, in NumPy
over the zero-copy host buffers of `diagnostics.field_view`, on a host build of peclet.flow.

Three revisions of the design (`--rev`, default 2):
  * rev 2 (the note's "Revision 2"): rev 1 without the instability guard. The window's Ritz radius
    has no consequence; the oracle still COMPUTES it on rev 1's eligible calls and records where
    rev 1 would have declared "unstable" (`ritz_would_fire`), as an instrument for the census.
    Iterates, step counts and K equal rev 1's wherever rev 1's guard did not fire (the guard
    never feeds back into gamma).
  * rev 1 (the note since its "Revision 1" section): velocity-only metric, P carried (mixed, not
    measured); phase A's target on the relative velocity residual; the Ritz guard only on mixed
    calls over windows of mixed columns and above max(1e-10, 1000 x tau), tau the inner tolerance;
    certification budget 2 (num_passes + 3) blocks with the early "slow" exit.
  * rev 0 (WO-1, the note's revision 0, reproduced bit for bit): the c_P-weighted W-metric with the
    fluid gauge, the guard on every active call above 1e-10, budget num_passes + 3.
`--metric`, `--ritz-scope`, `--ritz-action` and `--budget` override single pieces for ablation
(`--ritz-action fallback` = brief 3's alternative consequence: on "unstable", continue as the plain
march from the current plain output). Every run also sums the map's wall time and pressure
iterations (MAP_STATS) into its JSON record.

The rev-0 description, which rev 1 modifies as above:

  * §3   state vector (full padded buffers of u, v, w, p; roles Velocity / Pressure) and the
         W-metric (velocity at unit weight + c_P^2 x the fluid-centred, gauge-centred pressure),
         c_P = 1 / (mu_int + rho_int / dt_int) in the solver's internal units;
  * §4   type-II Anderson, one `step(accelerate)` = §4.3 steps 0-7 verbatim: change detection, the
         lazy MIX, the map, the provisional column, the reductions, the host decision (non-finite /
         restart / engagement), the commit and the next coefficients; §4.1 constants; §4.4
         solveTruncated (Jacobi-scaled cyclic-Jacobi eigendecomposition, oldest-column drop while
         the scaled condition < kCondMin); §4.6 the Ritz guard (Gelfand radius of I + XX^+ XR);
  * §7   the driver `march_to_steady` (phase A accelerate to (1 - slow_rate) rtol, phase B certify
         with the UNCHANGED §3.2 instrument on consecutive plain steps within num_passes + 3 blocks,
         target x 0.1 and resume on "budget", plain fallback on "growth" / stagnation / a status
         other than active). accelerate=False is the study's march() verbatim.

What the oracle cannot do, by construction (design note D1): the collocated face field uf_ is not in
the field registry, so a collocated run WITH advection (n_s = 7, §3.1 row 3) is refused here. The
parameter signature (internal dt, rho, mu, body force) has no Python getters; the oracle takes it
from the case that built the solver, which never changes it mid-march, so §4.3 step 0's signature
half can never fire in these runs (the inner-entry state check is implemented and live).

Cases (§11 of doc/collocated_invisible_subspace.md, as tests/study/study_avg_velocity_spheres.py
builds them: one sphere phi = 0.125 at the centre of a periodic unit cube, rho = mu = F = 1,
nu dt / h^2 = 6, Stokes; staggered Solver or SolverColocated with its AUTO = 'ghost' scheme):

    sphere   --scheme staggered|collocated --N 16 [--mu 1 --beta 6 | --dt ...] [--advection koren]
    bed      --scheme ...  the A1 dense random bed (design note §10 Q2), from an arrangement .npz

Settings (§8): --settings production (study: PCG(200, 1e-8), 200 velocity sweeps, rtol 1e-4) or
tight (PCG(400, 1e-12), velocity residual tolerance 1e-12, rtol 1e-10, max_steps 20000).

Run (from the flow tree, OpenMP pool bounded):

    OMP_NUM_THREADS=8 OMP_PROC_BIND=false PYTHONPATH=<flow host build> \\
        python tests/study/anderson_oracle.py sphere --scheme collocated --N 16 \\
        --settings production --window 0 3 5 8 [--json results.jsonl]

`--window 0` is the plain march (accelerate=False). Each run prints one summary line and, with
--json, appends one JSON record (steps, converged, reason, K, restarts, max Ritz radius over the
active range, max sum|alpha|, wall time, the residual trace).

Function Documentation

◆ run_map()

anderson_oracle.run_map ( solver )

One evaluation of the plain map, timed (the design's map is `solver.step()`, unchanged).

Definition at line 95 of file anderson_oracle.py.

Referenced by anderson_oracle.AndersonOracle.step().

◆ jacobi_eigh()

anderson_oracle.jacobi_eigh	(	A,
		tol = `1e-15`,
		max_sweeps = `50`
	)

Cyclic Jacobi eigendecomposition of a symmetric matrix, fixed sweep order (p < q, row-major).

Stops when the off-diagonal Frobenius norm is <= tol * ||A||_F, or after max_sweeps sweeps.
Returns (lam, V) with A = V diag(lam) V^T (columns of V are the eigenvectors).

Definition at line 106 of file anderson_oracle.py.

Referenced by scaled_eig().

◆ scaled_eig()

anderson_oracle.scaled_eig ( RR )

Jacobi scaling of §4.4 steps 1-3: D = diag(RR)^1/2, A = D^-1 RR D^-1. Returns (D, lam, V).

Definition at line 147 of file anderson_oracle.py.

References jacobi_eigh().

Referenced by pinv_truncated().

◆ cond_scaled()

anderson_oracle.cond_scaled ( lam )

Definition at line 155 of file anderson_oracle.py.

◆ solve_truncated()

anderson_oracle.solve_truncated	(	D,
		lam,
		V,
		b
	)

§4.4 step 5: y = sum_i v_i (v_i^T b~) / lam_i, gamma = D^-1 y, with b~ = D^-1 b.

Definition at line 160 of file anderson_oracle.py.

◆ pinv_truncated()

anderson_oracle.pinv_truncated ( XX )

§4.6: the truncated pseudo-inverse of §4.4 (Jacobi-scaled), eigenvalues below
kCondMin * lam_max discarded, no column dropping. A zero diagonal entry's row/column is the
pseudo-inverse's null part (it carries no direction).

Definition at line 167 of file anderson_oracle.py.

References scaled_eig().

◆ gelfand_radius()

anderson_oracle.gelfand_radius ( T )

§4.6 step 3: rho(T) ~ ||T^(2^20)||_max^(2^-20), renormalised every squaring.

Definition at line 186 of file anderson_oracle.py.

◆ march_to_steady()

anderson_oracle.march_to_steady	(		solver,
			monitor,
		*	rtol = `1e-4`,
			max_steps = `5000`,
			accelerate = `True`,
			window = `5`,
			check_every = `5`,
			num_passes = `3`,
			slow_rate = `0.997`,
			roundoff = `1e-11`,
			callback = `None`,
			oracle_kw = `None`,
			holder = `None`,
			budget = `None`,
			rev = `1`
	)

§7 driver. rev 0 = the note's revision 0 (certification budget num_passes + 3 blocks);
rev 1 = budget 2 (num_passes + 3) blocks plus the early "slow" exit: a failing block whose
ratio R lies in [slow_rate^check_every, 1) — a clean tail as slow as the instrument assumes,
failing on its remainder bound — resumes acceleration at once.

Definition at line 544 of file anderson_oracle.py.

Referenced by main().

◆ settings_of()

anderson_oracle.settings_of ( name )

Definition at line 664 of file anderson_oracle.py.

Referenced by main().

◆ build_solver()

anderson_oracle.build_solver	(		flow,
			scheme,
			N,
			sdf_fn,
			L,
		*	rho,
			mu,
			F,
			dt,
			advection,
			settings,
			vel_sweeps = `200`
	)

Definition at line 672 of file anderson_oracle.py.

Referenced by main().

◆ main()

anderson_oracle.main ( )

Definition at line 706 of file anderson_oracle.py.

References build_solver(), main(), march_to_steady(), mean(), and settings_of().

Referenced by main().

Variable Documentation

◆ K_MAX_WINDOW

int anderson_oracle.K_MAX_WINDOW = 8

Definition at line 76 of file anderson_oracle.py.

◆ K_ENGAGE_DECREASES

int anderson_oracle.K_ENGAGE_DECREASES = 2

Definition at line 77 of file anderson_oracle.py.

◆ K_RESTART_GROWTH

float anderson_oracle.K_RESTART_GROWTH = 4.0

Definition at line 78 of file anderson_oracle.py.

◆ K_MAX_RESTARTS

int anderson_oracle.K_MAX_RESTARTS = 5

Definition at line 79 of file anderson_oracle.py.

◆ K_NOISE_FLOOR

int anderson_oracle.K_NOISE_FLOOR = 1e-10

Definition at line 80 of file anderson_oracle.py.

◆ K_COND_MIN

int anderson_oracle.K_COND_MIN = 1e-12

Definition at line 81 of file anderson_oracle.py.

◆ K_RITZ_DELTA

int anderson_oracle.K_RITZ_DELTA = 1e-3

Definition at line 82 of file anderson_oracle.py.

◆ K_RITZ_HI

int anderson_oracle.K_RITZ_HI = 1e-2

Definition at line 83 of file anderson_oracle.py.

◆ K_RITZ_CONSECUTIVE

int anderson_oracle.K_RITZ_CONSECUTIVE = 3

Definition at line 84 of file anderson_oracle.py.

◆ K_GELFAND_SQUARINGS

int anderson_oracle.K_GELFAND_SQUARINGS = 20

Definition at line 85 of file anderson_oracle.py.

◆ K_RITZ_FLOOR_FACTOR

float anderson_oracle.K_RITZ_FLOOR_FACTOR = 1000.0

Definition at line 86 of file anderson_oracle.py.

◆ VELOCITY

anderson_oracle.VELOCITY

Definition at line 88 of file anderson_oracle.py.

◆ PRESSURE

anderson_oracle.PRESSURE

Definition at line 88 of file anderson_oracle.py.

◆ CARRIED

anderson_oracle.CARRIED

Definition at line 88 of file anderson_oracle.py.

◆ MAP_STATS

dict anderson_oracle.MAP_STATS = {"calls": 0, "seconds": 0.0, "pressure_iterations": 0}

Definition at line 92 of file anderson_oracle.py.

◆ L1

float anderson_oracle.L1 = 1.0

Definition at line 659 of file anderson_oracle.py.

◆ ZH_PHI

list anderson_oracle.ZH_PHI = [0.000125, 0.001, 0.008, 0.027, 0.064, 0.125, 0.216, 0.343, 0.45, 0.5236]

Definition at line 660 of file anderson_oracle.py.

◆ ZH_K

list anderson_oracle.ZH_K = [1.096, 1.212, 1.525, 2.008, 2.810, 4.292, 7.442, 15.4, 28.1, 42.1]

Definition at line 661 of file anderson_oracle.py.

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ run_map()

◆ jacobi_eigh()

◆ scaled_eig()

◆ cond_scaled()

◆ solve_truncated()

◆ pinv_truncated()

◆ gelfand_radius()

◆ march_to_steady()

◆ settings_of()

◆ build_solver()

◆ main()

Variable Documentation

◆ K_MAX_WINDOW

◆ K_ENGAGE_DECREASES

◆ K_RESTART_GROWTH

◆ K_MAX_RESTARTS

◆ K_NOISE_FLOOR

◆ K_COND_MIN

◆ K_RITZ_DELTA

◆ K_RITZ_HI

◆ K_RITZ_CONSECUTIVE

◆ K_GELFAND_SQUARINGS

◆ K_RITZ_FLOOR_FACTOR

◆ VELOCITY

◆ PRESSURE

◆ CARRIED

◆ MAP_STATS

◆ L1

◆ ZH_PHI

◆ ZH_K