Functions
	check (ok, what)

	build (name, spin, n=N, phi=PHI, beta=BETA, shift=(0.0, 0.0, 0.0))

	translating (name)

	spinning (name, steps=30)

	steady (s, probe, maxit=3000, tol=1e-9)

	spinning_steady (n, phi)

	translating_offset (n, phi, shift)

	agree (rows, key)

Variables
int	N = 24

float	PHI = 0.216

float	K_ZH = 7.442

float	BETA = 6.0

float	OMEGA_DT = 0.06

dict	SYSTEMS

int	TOL_X = 1e-10

int	TOL_ATOMIC = 1e-12

list	failures = []

dict	tr = {n: translating(n) for n in SYSTEMS}

	d = agree(tr, key)

dict	sp = {n: spinning(n) for n in SYSTEMS}

	ss = spinning_steady(32, 0.027)

	to = translating_offset(32, 0.027, (0.31, 0.17, 0.43))

Detailed Description

The hydrodynamic force and torque getters are unit-covariant, the public one is accurate, and
the traction diagnostic reads what it is documented to read.

The public getter is `hydro_force_torque_reaction()` (the discrete reaction). The traction
integral is the diagnostic `diagnostics.hydro_force_torque_traction()`; its old name
`hydro_force_torque()` is deprecated and must return the same array (2026-09-30, register
coupling.md "The public force API returns the reaction").

One sphere in a periodic cube (phi = 0.216, the regression's Zick & Homsy case) is solved in THREE
unit systems that pose the same index-space problem (the same viscous number beta = nu dt / h^2 = 6
and, for the spinning sphere, the same Omega dt):

  * "cell" -- no extent (spacing 1), rho 1, mu 0.1, dt 60, f 1e-3: the historical cell-unit API;
  * "unit" -- extent L = 1, rho = mu = f = 1;
  * "odd"  -- extent L = 7.3, rho 850, mu 0.037, f 2.5: no reference scale is 1.

Every DIMENSIONLESS number formed from a getter's output must then agree across the three systems
to round-off (the index-space arithmetic differs only by the scaling of its inputs). That is the gate that failed before 2026-09-30: `hydro_force_torque()`
applied the index -> physical conversion TWICE (force x forceTotalToPhys^2, torque x
torqueToPhys^2), which is the identity in cell units -- so every cell-unit gate passed -- and under
a physical domain read 0.0194 of the reaction at L = 1 and 3e-8 of it at L = 7.3.

Checks, translating sphere (body force along +x, marched to steady Stokes):
  1. K = f L^3 / (3 pi mu D U) within 1.5 % of Zick & Homsy's 7.442 (N = 24: -0.7 % measured);
  2. the reaction identity: sum F_reaction = f * V_fluid within 1 % (geometric V_fluid);
  3. traction / reaction in [0.60, 0.80] -- the documented resolution-independent ~29 % under-read
     (0.698 at N = 24 and 32);
  4. K, F_reaction / (f V_fluid), traction / reaction and the pressure / viscous split of the
     traction identical across the three systems to 1e-10 relative.
Spinning sphere (Omega about z, fixed step count -- the index-space states are proportional, not
steady):
  5. T_z / (mu a^3 Omega) from the reaction AND from the traction identical across the systems to
     1e-10 relative, and nonzero.
The names:
  6. the deprecated hydro_force_torque() returns what diagnostics.hydro_force_torque_traction()
     returns (shape (4, n, 3), equal to the atomics' round-off), and raises ONE DeprecationWarning
     that names hydro_force_torque_reaction().
Torque accuracy (unit system only, marched to steady Stokes):
  7. translating sphere on the vertex: the reaction torque is zero (|T| / (|F| R) < 1e-10);
  8. steadily spinning sphere, phi 0.027, N 32 (R/h 6): the reaction torque within (1.00, 1.04)
     of 8 pi mu a^3 Omega / (1 - phi) (1.0275 measured), the traction's in (0.50, 0.70) (0.593);
  9. translating sphere OFF the vertex (true torque zero, no discrete symmetry): the reaction's
     spurious |T| / (|F| R) below 3e-3 (1.1e-3 measured) and below the traction's (4.4e-3).

Run: OMP_NUM_THREADS=8 PYTHONPATH=<build> python tests/python/test_hydro_force_units.py
Exit 0 pass, 1 fail, 77 skipped (no module).

Function Documentation

◆ check()

test_hydro_force_units.check	(	ok,
		what
	)

Definition at line 77 of file test_hydro_force_units.py.

◆ build()

test_hydro_force_units.build	(	name,
		spin,
		n = `N`,
		phi = `PHI`,
		beta = `BETA`,
		shift = `(0.0, 0.0, 0.0)`
	)

Definition at line 83 of file test_hydro_force_units.py.

◆ translating()

test_hydro_force_units.translating ( name )

Definition at line 124 of file test_hydro_force_units.py.

◆ spinning()

test_hydro_force_units.spinning	(	name,
		steps = `30`
	)

Definition at line 160 of file test_hydro_force_units.py.

◆ steady()

test_hydro_force_units.steady	(	s,
		probe,
		maxit = `3000`,
		tol = `1e-9`
	)

March to steady Stokes: stop when probe() changes by < tol relative over 10 steps.

Definition at line 172 of file test_hydro_force_units.py.

◆ spinning_steady()

test_hydro_force_units.spinning_steady	(	n,
		phi
	)

Steady spinning sphere: T_z against the periodic-array value 8 pi mu a^3 Omega / (1 - phi)
(a rigid rotation sets the cell's mean vorticity, so the fluid counter-rotates at -phi Omega
to leading order; phi 0.008 and 0.027 at equal R/h agree to 3e-4 under this reference).

Definition at line 185 of file test_hydro_force_units.py.

◆ translating_offset()

test_hydro_force_units.translating_offset	(	n,
		phi,
		shift
	)

Steady translating sphere OFF the cell vertex: the true torque is zero, and no discrete
symmetry makes it so -- what is left is each getter's own torque error.

Definition at line 201 of file test_hydro_force_units.py.

◆ agree()

test_hydro_force_units.agree	(	rows,
		key
	)

Definition at line 215 of file test_hydro_force_units.py.

Variable Documentation

◆ N

int test_hydro_force_units.N = 24

Definition at line 61 of file test_hydro_force_units.py.

◆ PHI

float test_hydro_force_units.PHI = 0.216

Definition at line 62 of file test_hydro_force_units.py.

◆ K_ZH

float test_hydro_force_units.K_ZH = 7.442

Definition at line 63 of file test_hydro_force_units.py.

◆ BETA

float test_hydro_force_units.BETA = 6.0

Definition at line 64 of file test_hydro_force_units.py.

◆ OMEGA_DT

float test_hydro_force_units.OMEGA_DT = 0.06

Definition at line 65 of file test_hydro_force_units.py.

◆ SYSTEMS

dict test_hydro_force_units.SYSTEMS

Initial value:

=  {  # name: (L or None for cell units, rho, mu, f)
    "cell": (None, 1.0, 0.1, 1e-3),
    "unit": (1.0, 1.0, 1.0, 1.0),
    "odd": (7.3, 850.0, 0.037, 2.5),
}

Definition at line 66 of file test_hydro_force_units.py.

◆ TOL_X

int test_hydro_force_units.TOL_X = 1e-10

Definition at line 71 of file test_hydro_force_units.py.

◆ TOL_ATOMIC

int test_hydro_force_units.TOL_ATOMIC = 1e-12

Definition at line 72 of file test_hydro_force_units.py.

◆ failures

list test_hydro_force_units.failures = []

Definition at line 74 of file test_hydro_force_units.py.

◆ tr

dict test_hydro_force_units.tr = {n: translating(n) for n in SYSTEMS}

Definition at line 222 of file test_hydro_force_units.py.

◆ d

test_hydro_force_units.d = agree(tr, key)

Definition at line 236 of file test_hydro_force_units.py.

◆ sp

dict test_hydro_force_units.sp = {n: spinning(n) for n in SYSTEMS}

Definition at line 240 of file test_hydro_force_units.py.

◆ ss

test_hydro_force_units.ss = spinning_steady(32, 0.027)

Definition at line 251 of file test_hydro_force_units.py.

◆ to

test_hydro_force_units.to = translating_offset(32, 0.027, (0.31, 0.17, 0.43))

Definition at line 259 of file test_hydro_force_units.py.

Functions

Variables