Fluids (beta)¶
Viscous incompressible flow, heat carried by a flow and the Lorentz force on a conducting fluid in a magnetic field
obey the Navier-Stokes equations and their couplings. In this guide we solve such problems with
axionmultiphysics.fluids, an incompressible-flow library built on MFEM, and its builder axionmultiphysics.transport.
Both are beta: their interfaces may change, and their verification covers manufactured, closed-form and cross-code
problems but no published benchmark value or experiment. The module is compiled only in the MPI source build
(installation); axionmultiphysics.build_info()["fluids"] says whether a build has it.
Solvers¶
| feature | entry point | geometry | MPI ranks |
|---|---|---|---|
| Stokes, Taylor-Hood P2/P1 | fluids.solve_stokes |
planar; axisymmetric with swirl | solve on any number; point evaluation on one |
| 3D Stokes | fluids.solve_stokes_3d |
tetrahedra or hexahedra, optionally curved | distributed |
| steady Navier-Stokes | fluids.solve_navier_stokes |
planar; axisymmetric with swirl | solve on any number; point evaluation on one |
| inductionless MHD | fluids.solve_navier_stokes(..., geometry="planar25d", mhd={...}) |
planar 2.5D (z-invariant) | one |
| transient Navier-Stokes (BDF1/BDF2) | fluids.TransientNavierStokes |
planar; axisymmetric with swirl | time steps on any number; point evaluation on one |
| stabilized P1/P1 (GLS) | fluids.gls_problem, fluids.solve_gls |
planar, enclosed flows | one (serial) |
| steady scalar (heat) transport, SUPG | fluids.solve_heat, axionmultiphysics.transport.ScalarTransport |
planar; axisymmetric | one |
| steady Boussinesq natural convection | fluids.solve_boussinesq |
planar; axisymmetric | one |
Problems are set up in Python from meshes, coefficients and boundary conditions; there is no design-file, viewer or
MCP interface yet. The docstrings document the arguments (help(fluids.solve_navier_stokes)).
Channel and cavity flow¶
We solve a Poiseuille channel with the steady Navier-Stokes solver, whose exact solution it reproduces to round-off, and the lid-driven cavity at Re = 100, steady and integrated in time from rest:
import numpy as np
from axionmultiphysics import fluids
# 1. Poiseuille flow in a channel [0, 4] x [0, 1]: steady Navier-Stokes at Re = rho U H / mu = 100.
# Boundary attributes: 1 inflow (x = 0), 2 outflow (x = 4), 3 walls.
L, H, nx, ny = 4.0, 1.0, 32, 8
V = np.array([[x, y] for y in np.linspace(0, H, ny + 1) for x in np.linspace(0, L, nx + 1)])
vid = lambda i, j: j * (nx + 1) + i
tri = [t for j in range(ny) for i in range(nx)
for t in ([vid(i, j), vid(i + 1, j), vid(i, j + 1)], [vid(i + 1, j), vid(i + 1, j + 1), vid(i, j + 1)])]
seg = [[vid(i, 0), vid(i + 1, 0)] for i in range(nx)] + [[vid(i + 1, ny), vid(i, ny)] for i in range(nx)] \
+ [[vid(0, j + 1), vid(0, j)] for j in range(ny)] + [[vid(nx, j), vid(nx, j + 1)] for j in range(ny)]
att = [3] * (2 * nx) + [1] * ny + [2] * ny
mesh = fluids.Mesh.from_arrays(V, np.array(tri, np.int32), np.array(seg, np.int32), np.array(att, np.int32))
rho, mu = 1.0, 0.01 # dynamic units: density, dynamic viscosity
profile = lambda x, y: (4 * y * (H - y) / H**2, 0.0) # U = 1 on the centreline
sol = fluids.solve_navier_stokes(mesh, mu, rho, None, [
{"attribute": 1, "kind": "dirichlet", "value": profile},
{"attribute": 2, "kind": "do_nothing"}, # mu du/dn - p n = 0 (Laplacian form): p = 0 at the outlet
{"attribute": 3, "kind": "dirichlet"}], form="laplacian")
d = sol.diagnostics
el = np.arange(mesh.n_elements, dtype=np.int32) # evaluate at two reference points of every element
ref = np.array([[1 / 3, 1 / 3], [0.6, 0.2]])
x, _ = sol.geometry(el, ref)
u, _ = sol.velocity(el, ref)
p = sol.pressure(el, ref)
print("channel: converged", d["converged"], "| relative residual %.1e" % d["relative_residual"],
"| max velocity error %.1e" % np.max(np.abs(u[..., 0] - 4 * x[..., 1] * (H - x[..., 1]) / H**2)),
"| max pressure error %.1e" % np.max(np.abs(p - 8 * mu * (L - x[..., 0]) / H**2)))
# 2. Lid-driven cavity at Re = 100 on the unit square (attributes 1-4: bottom, right, top, left):
# the steady solution, and the flow started from rest and integrated in time with error control.
cavity = fluids.Mesh.unit_square(16)
lid = lambda x, y: (1.0 if y > 1 - 1e-12 else 0.0, 0.0)
walls = [{"attribute": a, "kind": "dirichlet", "value": lid} for a in (1, 2, 3, 4)]
steady = fluids.solve_navier_stokes(cavity, mu, rho, None, walls)
print("cavity, steady: converged", steady.diagnostics["converged"], "after", steady.diagnostics["iterations"],
"Newton steps")
ramp = lambda x, y, t: (min(t / 0.5, 1.0) * lid(x, y)[0], 0.0) # time-dependent data take (x, y, t)
ts = fluids.TransientNavierStokes(cavity, mu, rho, None, [dict(w, value=ramp) for w in walls])
ts.initialize(lambda x, y: (0.0, 0.0))
run = ts.adapt(10.0, 1e-3, 1.0, 0.01) # to t = 10: rtol, velocity scale, first step
el = np.arange(cavity.n_elements, dtype=np.int32)
du = ts.snapshot().velocity(el, ref)[0] - steady.velocity(el, ref)[0]
print("cavity, transient: t =", ts.time(), "after", len(run["times"]) - 1, "steps (%d rejected)" % run["rejected"],
"| max |u(t) - u_steady| %.1e" % np.max(np.abs(du)))
On one rank of an MPI build this prints (in a few seconds; the last digits can differ between builds), after the one-time beta warning on standard error:
channel: converged True | relative residual 1.5e-15 | max velocity error 1.1e-14 | max pressure error 3.8e-15
cavity, steady: converged True after 6 Newton steps
cavity, transient: t = 10.0 after 28 steps (1 rejected) | max |u(t) - u_steady| 4.8e-04
The parabolic profile lies in the P2 velocity space and the convective term vanishes on it, so the discrete solution is exact up to round-off; the cavity's transient solution approaches the steady one.
Conventions¶
- A mesh can also come from a model document:
axmp.mesh(d).instance(...).fluids_mesh()returns afluids.Meshthat copies the instance mesh, with the boundary attributes of its named boundaries (im.attributes[name],im.remaining_attributes,im.axis_attributes); see Meshes of model documents. - Meshes are 2D in the (x, y) plane (
fluids.Mesh.from_arrays,Mesh.unit_square,Mesh.annulus); axisymmetric problems use the meridional half plane(r, z) = (x, y), andfluids.Mesh3D.from_arraysbuilds 3D meshes. - Boundary conditions are a list of dicts, exactly one per boundary attribute; each solver's docstring lists the kinds it accepts.
solve_stokesandsolve_stokes_3dare kinematic (everything divided by the density); Navier-Stokes, the time stepper, MHD and Boussinesq take dynamic units (mu,rho, physical pressure).- No solver raises on non-convergence: we check
sol.diagnostics["converged"]. The fields of a solve that did not converge are refused. -
A steady Navier-Stokes or MHD solve with
strategy="newton"whose step stops reducing the residual at the round-off floor of its own residual evaluation (which can lie abovenewton_rtolon a fine mesh) stops there and counts as converged, provided the residual is still within a decade ofnewton_rtol. It says so:diagnostics["stopped_at_floor"]is then true anddiagnostics["residual_floor"]holds the measured floor. Soconvergedmeansdiagnostics["relative_residual"]is at mostnewton_rtol, or at most ten timesnewton_rtolwithstopped_at_floorset; a caller who needs the number itself reads it. The stop accepts the iterate it fired on, so the residual it reports can be a little larger than the one the full iteration budget would have wandered to (on the finest Ha = 0 level ofanalytic_hartmann_2dwith STRUMPACK: 1.14e-12 at the stop, 9.97e-13 after 22 steps without it). The measured floor depends on the number of MPI ranks at round-off level, so a solve sitting at the floor may stop a step earlier or later, and report a slightly different residual, on another rank count;convergedcan then differ between a serial and a parallel run.residual_floor_factor=0switches the rule off, andstrategy="picard"and"ptc", the time steps,solve_glsandsolve_boussinesqnever use it. The formulation notes derive the floor and list its measured values. -
A verdict rests on linear algebra, and the solvers report how accurate it was:
diagnostics["lu_residual_max"](the direct solves; each history entry has its ownlu_residual) anddiagnostics["mass_lu_residual_max"](the mass solves behind the dual norm). A final direct solve abovemax(newton_rtol, 1e-11)or a mass solve above1e-10makes the solve reportconverged = false, with the reason indiagnostics["failure"]. TransientNavierStokes.initialize()returnsFalsewhen the projection of the initial field onto the discretely divergence-free fields misses its accuracy gate (1e-13on the backward error of the projection solve, at everynewton_rtol, on any domain shape and in any length unit). We check that return value: after aFalse,advance,step_trial,adaptandsnapshotraise an error naming the projection.ts.diagnostics["projection_residual"]andts.diagnostics["projection_converged"]hold the residual and the verdict. STRUMPACK (the default direct solver of a build that has it) misses this gate on some scaled or stretched domains, depending on the processor; passlu="eigen"there (the error says so).quad_order_convection=0(the default) integrates the convective term exactly for the element shape and geometric order of the mesh; a rule that under-integrates it is refused.
3D Stokes is the only distributed solver; the 2D solves can run on several ranks, but their fields are evaluated on one, and transport, Boussinesq, MHD and GLS run on one rank. Turbulence models, compressible flow, induced magnetic fields and 3D Navier-Stokes are not implemented.
The walkthrough solves Stokes problems step by step against exact solutions. The formulation notes give the details of the Python interface, the equations, the discretization (including the stabilized equal-order elements) and the solvers, and the validation page lists the verification cases.