uf_advection_ab Namespace Reference

Functions
	tg_fields (N, nz, U0, amp, shift=0.0)
	packing_sdf (N, rfrac=0.18)
	div_periodic_faces (uf, vf, wf)
	div_of_advecting (s, use_uf)
	run_tg (cls, N, use_uf, nz=4, U0=1.0, steps=40, shift=0.0, dt=DT)
	tg_error (s, u0, N, nz, U0, steps, shift, dt)
	run_bed (cls, N, use_uf, steps, dt, mu=0.02, f0=1e-3)
	report_div (Ns=(32, 64))
	report_tg (Ns=(32, 64, 128), steps=40)
	report_shift (Ns=(32, 64), steps=120, shift=0.5, dt=0.1)
	report_bed (N=32, steps=200, dt=20.0)
	main ()

Variables
	flow = ensure_flow()
	NU
	DT
	RHO

Detailed Description

A/B of the COLLOCATED advecting velocity: the projected divergence-free MAC face field
`uf/vf/wf` (the shipped scheme) against the un-projected cell->face average 1/2(u_i+u_j) (the
phase-2 form, kept as `diagnostics.set_uf_advection(False)`).

Why this exists: `doc/flow_colocated_plan.md` §1 step 3 prescribes the projected field ("these u_f
become the advecting velocities for the next step's advection"), `colocated_advection.hpp` said the
swap was pending, and the FOU operator's conservative row-sum identity needs a divergence-free
advecting field (../docs/decisions/flow.md:977).  The swap landed 2026-09-21; this script is the
evidence behind it and the instrument for re-judging it.

Four measurements, each printed for BOTH choices:

  div    -- max |div_h(advecting field)| at the end of a Taylor-Green run.  This is the structural
            claim, not a tuning number: the projection makes `uf` solenoidal to solver tolerance,
            the cell->face average of the *corrected cell* field is not (the residual is intrinsic
            to cell-centred velocity placement -- it is why the coupling is an APPROXIMATE
            projection).  Measured here in Python on the same 7-point stencil `divergOpen` uses.
  tg     -- 2-D Taylor-Green in a triply-periodic box: an EXACT Navier-Stokes solution (the
            nonlinear term is balanced by the pressure gradient), so the L2 error and its observed
            order are absolute, not relative to a reference run.
  shift  -- the same vortex Galilean-shifted by a uniform mean velocity, no body force, periodic:
            the continuum answer is a mean momentum that is exactly constant, so any drift is the
            discrete advection failing to conserve.
  bed    -- the production regime the dt^2 scaling of the two choices' difference points at
            (../../amr/docs/amr_flow_uniform_parity.md §3a): steady large-dt driving through a
            cut-cell sphere bed, advection on, reported as <u_x> (proportional to permeability at
            fixed forcing) with the STAGGERED solver's answer on the same geometry as the
            reference -- the staggered stored velocity IS the projected face velocity, so it has
            no A/B to make and is the closest thing to a known answer here.

Run (host-openmp).  Use PYTHONPATH, not PECLET_FLOW_BUILD: the suite venv carries an INSTALLED
`peclet.flow`, and `_bootstrap`'s first rule (deliberately) keeps whatever is already importable,
so PECLET_FLOW_BUILD is ignored there and the study would silently measure the installed wheel.
Every run prints which module it resolved -- read that line before the numbers.

  OMP_NUM_THREADS=8 OMP_PROC_BIND=false PYTHONPATH=$PWD/build_uf \\
      python tests/study/uf_advection_ab.py [div|tg|shift|bed|all]

Function Documentation

tg_fields()

uf_advection_ab.tg_fields	(		N,
			nz,
			U0,
			amp,
			shift = 0.0
	)

Taylor-Green at decay amplitude `amp`, optionally Galilean-shifted in x by `shift`.

Definition at line 54 of file uf_advection_ab.py.

Referenced by run_tg(), and tg_error().

packing_sdf()

uf_advection_ab.packing_sdf	(		N,
			rfrac = 0.18
	)

The eight-sphere periodic bed of tests/regression/state_hash.py (same geometry, so the
numbers here and the byte gate's talk about the same scene).

Definition at line 67 of file uf_advection_ab.py.

Referenced by run_bed().

div_periodic_faces()

uf_advection_ab.div_periodic_faces	(		uf,
			vf,
			wf
	)

div_h of a MAC face field in flow's LOW-face convention (entry i = the -axis face of cell
i), on a fully periodic all-fluid block: (uf(i+1) - uf(i)) + ... , spacing 1.

Definition at line 86 of file uf_advection_ab.py.

Referenced by div_of_advecting().

div_of_advecting()

uf_advection_ab.div_of_advecting	(		s,
			use_uf
	)

max |div_h| of the field the advection operators actually read, on a periodic all-fluid box.

use_uf  -- the solver's own projected face field (`get_uf`/`get_vf`/`get_wf`, already the low-face
           convention).
else    -- the cell->face average `cadv::adv_vel` forms from the cell field: the LOW face of
           cell i is 1/2(u(i-1) + u(i)).

Definition at line 92 of file uf_advection_ab.py.

References div_periodic_faces().

Referenced by report_div().

run_tg()

uf_advection_ab.run_tg	(		cls,
			N,
			use_uf,
			nz = 4,
			U0 = 1.0,
			steps = 40,
			shift = 0.0,
			dt = DT
	)

Definition at line 109 of file uf_advection_ab.py.

References tg_fields().

Referenced by report_div(), report_shift(), and report_tg().

tg_error()

uf_advection_ab.tg_error	(		s,
			u0,
			N,
			nz,
			U0,
			steps,
			shift,
			dt
	)

L2 error against the exact decayed (and shifted) solution, normalized by the initial norm.

Definition at line 126 of file uf_advection_ab.py.

References tg_fields().

Referenced by report_tg().

run_bed()

uf_advection_ab.run_bed	(		cls,
			N,
			use_uf,
			steps,
			dt,
			mu = 0.02,
			f0 = 1e-3
	)

Steady large-dt driving through the cut-cell bed, advection ON and implicit (stable at a
dt far above the CFL limit -- the regime the two choices differ in).

Definition at line 137 of file uf_advection_ab.py.

References packing_sdf().

Referenced by report_bed().

report_div()

uf_advection_ab.report_div

(

Ns = (32, 64)

)

Definition at line 162 of file uf_advection_ab.py.

References div_of_advecting(), and run_tg().

Referenced by main().

report_tg()

uf_advection_ab.report_tg	(		Ns = (32, 64, 128),
			steps = 40
	)

Definition at line 172 of file uf_advection_ab.py.

References run_tg(), and tg_error().

Referenced by main().

report_shift()

uf_advection_ab.report_shift	(		Ns = (32, 64),
			steps = 120,
			shift = 0.5,
			dt = 0.1
	)

Definition at line 187 of file uf_advection_ab.py.

References run_tg().

Referenced by main().

report_bed()

uf_advection_ab.report_bed	(		N = 32,
			steps = 200,
			dt = 20.0
	)

Definition at line 203 of file uf_advection_ab.py.

References run_bed().

Referenced by main().

main()

uf_advection_ab.main

(

)

Definition at line 215 of file uf_advection_ab.py.

References main(), report_bed(), report_div(), report_shift(), and report_tg().

Referenced by main().

Variable Documentation

flow

uf_advection_ab.flow = ensure_flow()

Definition at line 48 of file uf_advection_ab.py.

NU

uf_advection_ab.NU

Definition at line 50 of file uf_advection_ab.py.

DT

uf_advection_ab.DT

Definition at line 50 of file uf_advection_ab.py.

RHO

uf_advection_ab.RHO

Definition at line 50 of file uf_advection_ab.py.