plic.hpp File Reference

core — PLIC (piecewise-linear interface construction) geometric toolbox: the analytic plane<->volume relation for a unit cell, interface-normal estimators, and slab truncation. More...

#include <Kokkos_Core.hpp>
#include <Kokkos_MathematicalFunctions.hpp>

Go to the source code of this file.

Classes
struct	peclet::core::vof::VofMetric
	The per-axis cell size, in the solver's reference length (hRef), of the cell these kernels map to the unit cube. More...

Namespaces
namespace	peclet
namespace	peclet::core
namespace	peclet::core::vof

Macros
#define	PECLET_VOF_C(dx, dy, dz)   c[plicSt(1 + (dx), 1 + (dy), 1 + (dz))]

Functions
double	peclet::core::vof::plicSq (double x)
double	peclet::core::vof::plicCube (double x)
double	peclet::core::vof::plicNormalizeL1 (double m[3])
	L1-normalize a normal in place. Returns the L1 norm before normalization (0 => untouched).
double	peclet::core::vof::vofPhysNormal (const double m[3], const VofMetric &g, double n[3])
	The PHYSICAL unit normal of an index-space normal m (any scale), i.e.
double	peclet::core::vof::vofPhysNormalInv (const double m[3], const VofMetric &g, double n[3])
	vofPhysNormal in the RECIPROCAL-MULTIPLY form — n = (H^-1 m) * (1/|H^-1 m|), which is what the curvature cascade's and the interface area's frame construction has always computed.
void	peclet::core::vof::vofIndexNormal (const double n[3], const VofMetric &g, double m[3])
	The INDEX-space normal of a physical normal n (any scale): m = H n, returned unnormalized (plicAlpha / plicVolume renormalize internally, so no L1 pass is needed).
double	peclet::core::vof::plicVolumeReduced (double w, double n1, double n2, double n3)
	Reduced-symmetry forward relation.
double	peclet::core::vof::plicVolume (double mx, double my, double mz, double alpha)
	Volume fraction of the unit cell [0,1]^3 lying on the fluid side m .
double	peclet::core::vof::plicAlphaReduced (double v, double n1, double n2, double n3)
	Reduced-symmetry analytic inverse of plicVolumeReduced.
double	peclet::core::vof::plicAlpha (double mx, double my, double mz, double v)
	Plane offset alpha such that plicVolume(mx,my,mz,alpha) == V, exactly (analytic inverse).
double	peclet::core::vof::plicSlabVolume (double mx, double my, double mz, double alpha, int dir, double a, double b)
	Fluid volume of the PLIC polyhedron inside the axis-aligned slab a <= x_dir <= b, expressed as a fraction of the WHOLE cell (so plicSlabVolume(..., 0, 1) == plicVolume(...)).
double	peclet::core::vof::plicBoxVolume (double mx, double my, double mz, double alpha, double a0, double b0, double a1, double b1, double a2, double b2)
	Fluid volume of the PLIC polyhedron inside the axis-aligned BOX [a0,b0] x [a1,b1] x [a2,b2], as a fraction of the WHOLE cell.
double	peclet::core::vof::faceFluxVolume (double mx, double my, double mz, double alpha, int dir, double f)
	Donor-cell geometric flux volume: the fluid volume swept out of the slab [0, f] along dir, as a fraction of the whole cell.
int	peclet::core::vof::plicSt (int i, int j, int k)
	Stencil index: x-fastest, offsets (i-1, j-1, k-1) with i,j,k in {0,1,2} (suite/docs/CONVENTIONS.md).
void	peclet::core::vof::youngsNormal (const double c[27], double m[3])
	Youngs' normal: the 27-point weighted gradient (corner 1, edge 2, face 4 on each of the two opposing planes), L1-normalized, pointing into the gas (m ~ -grad C).
void	peclet::core::vof::mycNormal (const double c[27], double m[3])
	MYC — Mixed Youngs-Centred normal (Aulisa et al.
double	peclet::core::vof::planeCellFraction (double mx, double my, double mz, double alphaGlobal, double x0, double y0, double z0, double h)
	Exact fluid fraction of the axis-aligned cell [x0,x0+h] x [y0,y0+h] x [z0,z0+h] under the GLOBAL plane m .
double	peclet::core::vof::planeCellFractionAniso (double mx, double my, double mz, double alphaGlobal, double x0, double y0, double z0, const VofMetric &g)
	The same for an anisotropic cell [x0, x0+g.h[0]] x [y0, y0+g.h[1]] x [z0, z0+g.h[2]]: the index normal of the global plane is H n (vofIndexNormal), so the exact fraction is one plicVolume call.
double	peclet::core::vof::sphereCellFraction (double cx, double cy, double cz, double r, double x0, double y0, double z0, double h, int levels)
	Fluid fraction of a cell for a sphere (fluid = INSIDE the sphere), by recursive octree subdivision with an exact tangent-plane closure at the leaves.

Detailed Description

core — PLIC (piecewise-linear interface construction) geometric toolbox: the analytic plane<->volume relation for a unit cell, interface-normal estimators, and slab truncation.

Container-free by contract. Every entry point here takes scalars and small local arrays only — no Kokkos::View, no grid indexing, no halo/topology types. That is what made the promotion to peclet::core::vof (done at WO-W0, see suite/docs/VOF_PLAN.md §11) a plain file move: the structured solver, the AMR octree and the per-bubble block container share ONE copy. Do not add container awareness to these signatures.

Convention

The cell is mapped to the unit cube [0,1]^3. A PLIC plane is

m . x = alpha ,   x in [0,1]^3

and the fluid (colour C = 1) side is the half-space m . x < alpha, i.e. m points into the gas, m ~ -grad(C). The canonical normalization is the L1 one, |mx| + |my| + |mz| = 1 (Scardovelli & Zaleski's choice), and every normal returned here is L1-normalized. The plane<->volume routines do NOT require it: they renormalize internally, so any nonzero m with a consistently scaled alpha gives the same answer (the relation V(m, alpha) is invariant under (m, alpha) -> (lambda m, lambda alpha)). That is what makes plicSlabVolume a two-line rescale rather than a polyhedron clipper.

Algorithm sources (followed, not approximated)

• Forward plicVolume — Scardovelli & Zaleski, JCP 164:228 (2000), in the branch-reduced GPU form of Lehmann & Gekle, Computation 10:21 (2022) [arXiv:2006.12838], their eq. (11) and Listing 1 (plic_cube_inverse): mirror to the positive octant, sort |m| ascending, fold V > 1/2 onto V < 1/2, then five piecewise-cubic cases.
• Inverse plicAlpha — the analytic SZ inversion in Lehmann & Gekle's optimized L1 form, their Listing 4 (plic_cube_reduced): closed forms for cases (5), (2), (1) and a single trigonometric branch covering the two cubic cases (3) and (4).
• youngsNormal / mycNormal — Youngs' 27-point weighted gradient and the Mixed Youngs-Centred scheme of Aulisa, Manservisi, Scardovelli & Zaleski, JCP 225:2301 (2007), transcribed from the reference implementation basilisk/src/myc.h (authored by Scardovelli himself).

The two cubic branches were re-derived independently when this file was written (substitute d = c + u into the case (3)/(4) volume polynomial, obtain the depressed cubic u^3 - 3 t^2 u + (a + 3 b c - 2 c^3) = 0 with t = sqrt(c^2 - b), and solve it with u = -2 t sin(asin((c^3 - a/2 - 3 b c/2)/t^3)/3) via sin 3psi = 3 sin psi - 4 sin^3 psi); the derivation reproduces Listing 4 term for term, so the transcription is verified and not merely copied.

**Layer L1 (VOF_PLAN.md §11): promoted from flow/src/vof/ to core (WO-W0, 2026-09-02).** These are the container-free VoF math kernels — one copy shared by every container: flow's structured colour field, the per-bubble block container (Part III) and the future AMR path. flow/src/vof/plic.hpp is now a thin include + a using-directive, so every existing peclet::flow::vof:: spelling keeps working unchanged.

Definition in file plic.hpp.

Macro Definition Documentation

PECLET_VOF_C

#define PECLET_VOF_C	(		dx,
			dy,
			dz
	)		c[plicSt(1 + (dx), 1 + (dy), 1 + (dz))]

Definition at line 389 of file plic.hpp.