Classes
class	Path

class	StderrCapture

Functions
	F (a)

	tg_force ()

	slab_rho (ratio)

	drop_colour ()

	channel_sdf ()

	vel (s)

	cb_amp (d)

	g2 (path, dt, walls=False)

	march (path, s)

	restore (s, state)

	g3 (path)

	paths ()

	guarded (path, fn, *args)

	main (argv)

	test_collocated_stability_guard ()

Variables
	N

	NZ

float	MU = 1.0

int	EPS = 1e-3

int	FLOOR = 1e-9

int	A_TG = 1e-4

int	SIGMA = 1e-6

float	KAPPA = 0.25

tuple	G2_DTS = (0.1, 100.0)

float	G2_WALLED_DT = 100.0

tuple	G3_DTS = (100.0, 10.0, 1.0)

int	G2_STEPS = 100

int	G3_MAX_STEPS = 3000

int	G3_TOL = 1e-10

int	G3_GATE = 1e-7

int	P_RTOL = 1e-12

str	FALLBACK = "AUTO scheme fell back"

dict	REFUSAL_WHITELIST = {}

Detailed Description

Guard: every COLLOCATED density path is stable at large mu*dt and has a dt-independent steady
state (doc/collocated_varrho_forces.md §7.6; suite-wide register "Collocated forces stay in the
implicit predictor").

Why a gate and not a grep. The defect this guards against is a property of the discrete STEP: where
the lagged pressure enters relative to the implicit momentum operator. Added as a face acceleration
AFTER the viscous solve (Basilisk centered.h; flow's rung V8/WO-T until 2026-09-25), the lagged
pressure lies exactly in the range the projection removes, so the velocity update is
non-incremental: with the rotational update the pressure obeys P^{n+1} = -4 kappa dt S P^n / rho,
growing ~12 kappa dt/(rho h^2) per step at (pi, pi, pi) once mu dt/(rho h^2) > 1/12 (G2); with
kappa = 0 the steady state depends on dt (G3). The form can come back under any name -- a
centered.h port, an "explicit pressure correction after the viscous solve", a defect-correction
stage that moves -G P^n to a later explicit update -- and none share a token; both signatures are
unconditional.

Paths:
  constant rho: 'ghost' (PINNED, and the build must print no AUTO fallback notice: G2 in the
  periodic all-fluid box, G3 with the +-y walls made by an immersed solid, because the ghost v1
  does not take domain-BC walls and an AUTO request there silently runs gauge-exact),
  'gauge-exact', 'plain', 'embed';
  V8 variable rho: a uniform rho field and a frozen ratio-1000 slab, balanced-force projection
  OFF and ON; V8 constant-rho CSF (enable_vof, sigma > 0, C re-set before every step = frozen,
  constant kappa), OFF and ON. The ON variants are reported as unavailable on a build without
  set_balanced_force_projection.
A throw FAILS the path, at any step, unless the path is in REFUSAL_WHITELIST (a documented scope
refusal; empty today: every path above is in scope). A refusal used to count as a pass, which let a
path that throws at its first step pass silently.

Protocol, Stokes (advection off, so the step is affine and a perturbation evolves exactly by the
step operator); mu = 1, rho_min = 1, h = 1; a small Taylor-Green cell force keeps the twin non-trivial.
  G2 growth: seed P with eps (-1)^(x+y+z) + eps * U(-1, 1) and run 100 steps at dt in
     {0.1, 100} beside the unseeded twin (periodic; the ratio-1000 slab OFF also WALLED at +-y
     at dt = 100, so the weight sum, the high-face openness and the Neumann rho ghosts are in it --
     once: the option does not touch the homogeneous step operator that G2 measures, ON and OFF
     give the same growth numbers, and OFF also runs on a build without the option). Measured: the (pi,pi,pi) FFT amplitude of P - P_twin
     and max|u - u_twin|. Pass iff at step 100 both are <= 2x their reference and <= (1 + 1e-6)x
     their step-50 value. Reference: the seeded amplitude for P; for u (zero before the first step)
     its value after step 1. Values below a round-off floor FLOOR*eps count as the floor (a decayed
     transient is noise, not growth).
  G3 dt-independence: walled at +-y, the Taylor-Green force, dt in {100, 10, 1}. The dt = 100 run
     marches to max|du| <= 1e-10 max|u| -- from rest, or for a V8 ON path from the OFF path's
     converged dt = 100 state (u, v, w, P without P_b: the first ON step re-splits); the dt = 10
     and dt = 1 runs are WARM-STARTED from the dt = 100 state (u, v, w, P, and P_b when the option
     is on) and march to the same criterion. A dt-independent fixed point is then already
     converged (one or two steps); a dt-dependent one drifts. Pass iff
     max|u(dt_i) - u(dt_j)| <= 1e-7 max|u| -- the Chorin signature this catches is 2.5e-2 to 0.5,
     so the gate keeps five decades of margin above the 1e-10 march tolerance. (Warm starting is
     what makes the ratio-1000 slab affordable: from rest its heavy layer relaxes at rate
     mu k^2/rho ~ 1e-4 per unit time.) Every march must converge within G3_MAX_STEPS or the path
     fails. Pressure rtol 1e-12 throughout.

Run:  OMP_NUM_THREADS=4 OMP_PROC_BIND=false PYTHONPATH=<build> \
          python tests/python/test_collocated_stability_guard.py
Exit 0 pass, 1 fail, 77 skipped (no module).

Function Documentation

◆ F()

test_collocated_stability_guard.F ( a )

Definition at line 91 of file test_collocated_stability_guard.py.

◆ tg_force()

test_collocated_stability_guard.tg_force ( )

Definition at line 95 of file test_collocated_stability_guard.py.

Referenced by test_collocated_stability_guard.Path._build().

◆ slab_rho()

test_collocated_stability_guard.slab_rho ( ratio )

Definition at line 103 of file test_collocated_stability_guard.py.

Referenced by paths().

◆ drop_colour()

test_collocated_stability_guard.drop_colour ( )

Volume fractions of a sphere, R = 4, 4x4x4 sub-sampling (frozen interface for the CSF).

Definition at line 109 of file test_collocated_stability_guard.py.

◆ channel_sdf()

test_collocated_stability_guard.channel_sdf ( )

Immersed-solid walls at y = 1 and y = N - 1 (face-aligned), fluid between: the ghost
scheme's G3 walls (it does not take domain-BC walls).

Definition at line 149 of file test_collocated_stability_guard.py.

Referenced by test_collocated_stability_guard.Path._build().

◆ vel()

test_collocated_stability_guard.vel ( s )

Definition at line 225 of file test_collocated_stability_guard.py.

Referenced by g2(), and march().

◆ cb_amp()

test_collocated_stability_guard.cb_amp ( d )

(pi, pi, pi) Fourier amplitude of a cell field.

Definition at line 229 of file test_collocated_stability_guard.py.

Referenced by g2().

◆ g2()

test_collocated_stability_guard.g2	(	path,
		dt,
		walls = `False`
	)

Returns (ok, text).

Definition at line 234 of file test_collocated_stability_guard.py.

References cb_amp(), F, and vel().

◆ march()

test_collocated_stability_guard.march	(	path,
		s
	)

Definition at line 265 of file test_collocated_stability_guard.py.

References vel().

Referenced by g3().

◆ restore()

test_collocated_stability_guard.restore	(	s,
		state
	)

Definition at line 278 of file test_collocated_stability_guard.py.

References F.

Referenced by g3().

◆ g3()

test_collocated_stability_guard.g3 ( path )

Definition at line 284 of file test_collocated_stability_guard.py.

References march(), and restore().

◆ paths()

test_collocated_stability_guard.paths ( )

Definition at line 319 of file test_collocated_stability_guard.py.

References slab_rho().

Referenced by main().

◆ guarded()

test_collocated_stability_guard.guarded	(		path,
			fn,
		*	args
	)

Run one gate; a throw fails it unless the path is whitelisted to refuse.

Definition at line 332 of file test_collocated_stability_guard.py.

Referenced by main().

◆ main()

test_collocated_stability_guard.main ( argv )

Definition at line 342 of file test_collocated_stability_guard.py.

References guarded(), and paths().

◆ test_collocated_stability_guard()

test_collocated_stability_guard.test_collocated_stability_guard ( )

Definition at line 376 of file test_collocated_stability_guard.py.

References main().

Variable Documentation

◆ N

test_collocated_stability_guard.N

Definition at line 70 of file test_collocated_stability_guard.py.

◆ NZ

test_collocated_stability_guard.NZ

Definition at line 70 of file test_collocated_stability_guard.py.

◆ MU

float test_collocated_stability_guard.MU = 1.0

Definition at line 71 of file test_collocated_stability_guard.py.

◆ EPS

int test_collocated_stability_guard.EPS = 1e-3

Definition at line 72 of file test_collocated_stability_guard.py.

◆ FLOOR

int test_collocated_stability_guard.FLOOR = 1e-9

Definition at line 73 of file test_collocated_stability_guard.py.

◆ A_TG

int test_collocated_stability_guard.A_TG = 1e-4

Definition at line 74 of file test_collocated_stability_guard.py.

◆ SIGMA

int test_collocated_stability_guard.SIGMA = 1e-6

Definition at line 75 of file test_collocated_stability_guard.py.

◆ KAPPA

float test_collocated_stability_guard.KAPPA = 0.25

Definition at line 76 of file test_collocated_stability_guard.py.

◆ G2_DTS

tuple test_collocated_stability_guard.G2_DTS = (0.1, 100.0)

Definition at line 77 of file test_collocated_stability_guard.py.

◆ G2_WALLED_DT

float test_collocated_stability_guard.G2_WALLED_DT = 100.0

Definition at line 78 of file test_collocated_stability_guard.py.

◆ G3_DTS

tuple test_collocated_stability_guard.G3_DTS = (100.0, 10.0, 1.0)

Definition at line 79 of file test_collocated_stability_guard.py.

◆ G2_STEPS

int test_collocated_stability_guard.G2_STEPS = 100

Definition at line 80 of file test_collocated_stability_guard.py.

◆ G3_MAX_STEPS

int test_collocated_stability_guard.G3_MAX_STEPS = 3000

Definition at line 81 of file test_collocated_stability_guard.py.

◆ G3_TOL

int test_collocated_stability_guard.G3_TOL = 1e-10

Definition at line 82 of file test_collocated_stability_guard.py.

◆ G3_GATE

int test_collocated_stability_guard.G3_GATE = 1e-7

Definition at line 83 of file test_collocated_stability_guard.py.

◆ P_RTOL

int test_collocated_stability_guard.P_RTOL = 1e-12

Definition at line 84 of file test_collocated_stability_guard.py.

◆ FALLBACK

str test_collocated_stability_guard.FALLBACK = "AUTO scheme fell back"

Definition at line 85 of file test_collocated_stability_guard.py.

◆ REFUSAL_WHITELIST

dict test_collocated_stability_guard.REFUSAL_WHITELIST = {}

Definition at line 88 of file test_collocated_stability_guard.py.

Classes

Functions

Variables