API reference

Shared supertype of the vfrac-stencil neighborhoods (enables a generic auto-guess).

Region

Which side of a separator a moment refers to: Internal (normal·x ≤ d) or External.

3-vector type used throughout the API for points, normals, and centroids.

Append every moment of other to l (IRL takes other non-const).

Copy the buffer's current contents out as a Vector{UInt8}.

resize!(b::ByteBuffer, n) -> b

Set the buffer's size to n bytes. Use before unpacking into b from an external source (e.g. after an MPI receive tells you the incoming length).

addmember!(neigh, cell, value) -> neigh

Append a stencil member (assigned the next 0-based index in insertion order).

addpath!(g::PlanarSeparatorPathGroup, p::PlanarSeparatorPath[, id]) -> g

Add p to the group. With id, the path is registered under that phase id (IRL's addPlanarSeparatorPath overload taking an explicit tag).

addplane!(sep_or_loc, normal, distance) -> sep_or_loc

Append the plane {x : normal·x = distance} (length-3 normal).

adjust_cap_to_match_volume!(p, signed_volume) -> p

Move the "cap" vertex of a capped polytope so volume(p) equals signed_volume.

This is what makes a semi-Lagrangian flux volume conservative: build the flux polyhedron from back-projected face vertices, then pin its volume to the exact face flux u·n A Δt. Available on the capped/symmetric polytopes (CappedDodecahedron*, CappedOctahedron_*, Polyhedron24*, SymmetricHexahedron, SymmetricTriangularPrism).

at_tag(c::TaggedAccumulatedVolume2, tag) -> TaggedAccumulatedVolume

The inner tag→volume map stored under region tag. Aliases into c.

calculate_plane_of_existence!(p) -> p

Recompute the plane of existence from the polygon's current points.

calculate_sign(p) -> Float64

Sign of the polygon's area relative to its plane of existence.

clear!(c) -> c

Drop all entries, leaving an empty collection ready to be refilled.

connect!(link, edge, other) -> link

Wire link's edge-th neighbour to other (0-based edge index).

connect!(p::PlanarSeparatorPath, other) -> p

Point p at its downstream path in the separator chain.

connect_null!(p::PlanarSeparatorPath) -> p

Terminate the chain at p.

Return the Ref{c_*} that a high-level wrapper forwards to ccall.

cut_volume(poly, sep) -> Float64

Volume of poly internal to sep (the scalar getNormMoments … Vol cutters).

deserialize(::Type{PlanarSeparator}, b::ByteBuffer) -> PlanarSeparator

Reconstruct a PlanarSeparator from a packed buffer.

getdata(p, i) -> Vec3

Per-vertex data 3-vector at vertex i (1-based) of a doubles3 polytope.

getid(link) -> Int

The link's mesh id.

getplane(s::PlanarSeparator, i) -> (normal::Vec3, distance)

The i-th plane. 1-based (Julia convention).

getpt(p, i) -> Vec3

The i-th defining point of a polytope. 1-based (Julia convention).

getsimplex(p, i) -> Triangle

The i-th triangle (1-based) of the simplex decomposition.

importances(w::R2PWeighting) -> NamedTuple

Read back the configured R2P objective weights.

interface_area(cell::RectangularCuboid, sep::PlanarSeparator) -> Float64

Total interfacial area inside cell — summed over all of sep's planes, so unlike interface_divided_polygon this handles a two-plane (R2P) separator in one call. Zero when the cell holds no interface.

interface_divided_polygon(cell::RectangularCuboid, sep; plane = 1) -> DividedPolygon

As interface_polygon, but returns the triangulated form — the one that carries surface_area.

interface_polygon(cell, sep::PlanarSeparator; plane = 1) -> Polygon

The polygon where sep's plane-th interface plane (1-based) cuts cell.

Cells: RectangularCuboid, Tet, Hexahedron. Returns an empty polygon (npts == 0) when the plane misses the cell — a cell that is entirely liquid or entirely gas has no interface. The result's plane of existence is set, so volume (signed area), centroid, and normal are immediately valid.

internal_volume(poly, sep) -> Float64

Alias of cut_volume: the volume of poly on the internal side of sep.

is_point_internal(pt, sep::PlanarSeparator) -> Bool
is_point_internal(pt, loc::PlanarLocalizer) -> Bool

Whether pt lies on the internal side of every plane — inside the separator's liquid region, or inside the localizer's cell.

localizer(p) -> PlanarLocalizer

A localizer bounding the polygon (its plane plus its edge planes).

localizer_from_cuboid(lower, upper) -> PlanarLocalizer

A localizer whose six planes bound the axis-aligned box [lower, upper].

locate_point(pt, link) -> Int

Walk the link graph from link and return the id of the node whose localizer contains pt (the id set with setid!).

This is the lookup a semi-Lagrangian scheme needs after back-projecting a point: given a departure point, which cell did it come from? Works on LocalizedSeparatorLink and LocalizedSeparatorGroupLink. The walk starts at link, so pass a node near pt to keep it short.

match_group_volume_fraction!(group::PlanarSeparatorPathGroup, cell, vfracs;
                             tolerance = nothing) -> group

Multi-phase volume-fraction matching: set every separator in group so that cell's phase fractions equal vfracs (one entry per phase, in the group's priority order). Cells: Tet, Hexahedron, Pyramid, TriangularPrism.

match_volume_fraction!(sep::PlanarSeparator, cell, vfrac; tolerance = nothing) -> sep

Adjust sep's plane distance so cell's internal fraction equals vfrac. With tolerance, IRL's iterative distance search stops at that volume-fraction error instead of the library default.

moments!(out, poly, sep) -> out

Fill out with the un-normalized moments of poly cut by sep.

moments_at_tag(c, tag) -> SeparatedMoments

The moments accumulated against region tag — for a flux-volume cut, the liquid and gas contributed by the donor cell with that id. Unlike c[i], the lookup is by IRL's raw tag, so you can ask for a specific donor without scanning tags(c). The result aliases into c, which it retains.

nearest_point_on_surface(p::Polygon, pt) -> Vec3

The point of p closest to pt.

norm_moments!(out, poly, sep) -> out

Fill out with the normalized moments of poly cut by sep.

nsimplices(p) -> Int

Number of triangles in the polygon's simplex decomposition.

parameters(o::OptimizationBehavior) -> NamedTuple

Read back every configured optimizer parameter.

plane_of_existence(p) -> (normal::Vec3, distance)

The plane the polygon's points are taken to lie in.

print_to_screen(x) -> x

Dump x using IRL's internal C++ printer. Output goes to the process's stdout directly, bypassing Julia's IO — it will not appear in a redirected IOBuffer. Defined for the types whose C interface provides printToScreen.

priority_order(g::PlanarSeparatorPathGroup) -> Vector{Int}

The group's current phase priority order, as tags.

reconstruct_advected_normals(moments::ListedVolumeMoments, n::R2PNeighborhood,
                             two_plane_threshold; debug = false) -> PlanarSeparator

Reconstruct from transported interface normals rather than from volume fractions alone. moments holds the advected VolumeMomentsAndNormal entries (typically the output of a doubles3 / VMAN flux-volume cut); two_plane_threshold decides when the result becomes a two-plane (R2P) separator instead of a single plane.

reconstruct_elvira(n::ELVIRANeighborhood; dims=3) -> PlanarSeparator

ELVIRA reconstruction from a stencil of liquid volume fractions.

reconstruct_lvira(neigh, guess_or_center_moments; dims=3) -> PlanarSeparator

Non-mutating LVIRA. Pass either an explicit PlanarSeparator guess, or the centre cell's SeparatedMoments — in which case IRL's barycentre initial guess (normalize(gas_centroid − liquid_centroid), then match VF) is built, exactly as IRL's own driver does. Requires set_center_of_stencil! for the latter.

reconstruct_lvira!(guess::PlanarSeparator, neigh; dims=3) -> guess

Refine guess in place via LVIRA against the neighborhood's volume fractions.

reconstruct_mof(cell, moments::SeparatedMoments; dims = 3) -> PlanarSeparator
reconstruct_mof(cell, moments, w_internal, w_external; dims = 3) -> PlanarSeparator

Moment-of-Fluid reconstruction: the single-plane separator for cell whose internal region reproduces moments. The 4-arg form is the geometrically- weighted (GW) variant.

Cells depend on dims: 3D takes Tet, Hexahedron, RectangularCuboid; 2D takes RectangularCuboid and Triangle (IRL's planar MOF, which constrains the interface normal to the x–y plane).

reconstruct_r2p!(guess::PlanarSeparator, n::R2PNeighborhood; dims=3,
                 weighting=nothing, behavior=nothing) -> guess

R2P reconstruction — like LVIRA, an optimizer that refines an initial-guess separator in place against the neighborhood's separated moments. With a weighting::R2PWeighting (and optionally a behavior::OptimizationBehavior) the weighted 3D solver is used.

reconstruct_r2p(n::R2PNeighborhood[, guess]; dims=3, kwargs...) -> PlanarSeparator

Non-mutating R2P. With no guess, IRL's barycentre initial guess is built from the centre cell's stored moments (requires set_center_of_stencil!).

Register jl as the wrapper for C handle symbol csym (e.g. :c_Tet).

reverse_pt_ordering!(p) -> p

Reverse the vertex winding, flipping the sign of the area/normal.

separated_moments(poly, sep::PlanarSeparator) -> SeparatedMoments

Cut poly by sep and return internal & external volume + centroid. Available for shapes with a *_PlanarSep_SepVM cutter (RectangularCuboid, Hexahedron, Dodecahedron).

serialize(sep::PlanarSeparator) -> ByteBuffer

Pack sep into a fresh ByteBuffer (rewound and ready to read).

set_center_of_stencil!(neigh, index) -> neigh

Mark the centre cell by its 0-based stencil index (e.g. 13 for a 3×3×3 stencil), matching IRL.

set_cutting_method!(m::CuttingMethod)

Select the algorithm used by subsequent cutting calls.

set_importances!(w::R2PWeighting; liquidvolumefraction, liquidcentroidrelativetogas,
                 centroid, surfacearea) -> w

Set all four R2P objective weights at once. Any omitted keyword keeps its current value.

set_minimum_surface_area_to_track!(area) -> area

As set_minimum_volume_to_track!, for interface surface area.

set_minimum_volume_to_track!(vol) -> vol

Cut regions smaller than vol are discarded rather than accumulated. Guards the tagged-accumulation collections against filling with numerical dust.

set_nplanes!(sep_or_loc, n) -> sep_or_loc

Resize the plane list to n. Newly exposed planes are uninitialised — set each with setplane! before use.

set_plane_of_existence!(p, normal, distance) -> p

Assert the polygon's plane of existence instead of deriving it from the points.

set_priority_order!(g::PlanarSeparatorPathGroup, tags) -> g

Set the order in which the group's phases are resolved, as a vector of phase tags (IRL's raw tag values, not 1-based positions).

set_vf_bounds!(low) -> low

Volume fractions below low (or above 1 - low) are snapped to pure gas / pure liquid, so a cell never carries a sliver of the other phase.

set_vf_tolerance!(tol) -> tol

Convergence tolerance for IRL's iterative distance finding — how exactly match_volume_fraction! must hit its target fraction.

setdata!(p, i, d) -> p

Set the per-vertex data 3-vector at vertex i (1-based).

setid!(link, id) -> link

Assign the link's mesh id.

setmember!(neigh, index_or_ijk..., cell, value) -> neigh

Place a stencil member. Stencil indices are 0-based (IRL convention): a linear index in 0:N-1 for LVIRA/R2P, or (i, j, k) ∈ {-1,0,1} for ELVIRA.

setplane!(sep_or_loc, i, normal, distance) -> sep_or_loc

Overwrite the i-th plane (1-based) in place, rather than appending as addplane! does. The plane count must already cover i — grow it first with set_nplanes!. Reusing a separator this way avoids reallocating one per cell per timestep.

setpt!(p, i, pt) -> p

Overwrite vertex i (1-based) in place. Defined for the polytopes whose C interface exposes a point setter (Polyhedron24, and the doubles3 types) — useful to avoid reallocating a flux volume every timestep.

vertices(p) -> Matrix{Float64}

All defining points as a 3×N matrix (columns = vertices). Uses IRL's bulk getVertices where available; falls back to repeated getpt.

zero_normal_component!(l::ListedVolumeMoments, i) -> l

Zero the i-th entry's normal (1-based) — used to drop a spurious plane before feeding the list to reconstruct_advected_normals.

zero_polygon!(p) -> p

Drop all points, leaving an empty polygon.

@wrap JuliaName c_prefix

Define mutable struct JuliaName wrapping Ref{c_prefix} with a zero-argument constructor that calls c_prefix_new, a finalizer calling c_prefix_delete, and registration in _JLTYPE. Zero-arg construction fits the many IRL objects that are created empty and then filled by a cutter.