peclet-amr 0.2.0
Block-local-Morton AMR octree + collocated cut-cell Navier–Stokes solver (header-only C++20, Kokkos + MPI)
Loading...
Searching...
No Matches
peclet::amr::oracle::AmrFlow< Bits > Class Template Reference

#include <flow_oracle.hpp>

Public Types

using Octree = BlockOctree< 3, Bits >
 

Public Member Functions

void init (const Octree &t, Real h0, Vec< 3 > origin=Vec< 3 >{})
 
void init (const Octree &t, const Vec< 3 > &h0, Vec< 3 > origin=Vec< 3 >{})
 
void setDensity (double rho)
 
void setViscosity (double mu)
 
void setDt (double dt)
 
void setBodyForce (double fx, double fy, double fz)
 
void setAdvection (bool on)
 
void setAdvectionScheme (int s)
 High-order advection scheme: 0 = second-order upwind (SOU, default), 1 = Koren TVD.
 
void setImplicitAdvection (bool on)
 Implicit-FOU deferred-correction advection (default ON): the first-order-upwind part is solved implicitly (in the momentum operator) and the high-order − FOU difference is explicit — unconditionally stable for advection.
 
void setGhostGradient (bool on)
 Directional ghost cell-gradient for the −∇pⁿ predictor and the projection's cell correction (the AMR analog of flow's collocated set_face_interp(9) hybrid): on cells with a solid-centered axis neighbour, gradOf reads the DECOUPLED p=0 of that neighbour through partially-open faces — a gauge-dependent O(1/h) gradient error at cut cells (measured in tests/study_amr_ghost_apriori.cpp).
 
void setApertureOrder (int order)
 FULL directional ghost-cell projection (the AMR port of flow's collocated set_ghost_projection): the pressure system becomes rho·(L_bin + Delta) phi = rho·D_g(u*) — the BINARY-openness FV Laplacian (preconditioned by the unchanged openness MG) plus the wall-anchored closure overlay on the finest-band rows, solved by MG-preconditioned BiCGStab; the constraint is the ghost-closed divergence of the ½/½ face-averaged field.
 
void setGhostProjection (bool on, int matrixOrder=2, int rhsOrder=2)
 
void setGhostSampled (bool on)
 SAMPLED ghost projection: the mixed-level cut-band prototype (the D1 machinery of docs/amr_mixed_level_cut_band_plan.md — cut cells at MULTIPLE octree levels, chain entries across 2:1 boundaries replaced by degree-2 LS virtual samples).
 
void setCfScheme (int scheme)
 Coarse/fine (2:1) interface scheme (cf_scheme.hpp): 0 = standard two-point flux (default, 1st-order at level boundaries, bit-identical legacy path), 1 = Martin–Cartwright tangential quadratic (2nd-order).
 
double advectTerm (int comp, Index i) const
 Conservative Koren-TVD advection term ∇·(u u_comp) at leaf i (physical units; the explicit momentum advection).
 
template<class SdfFn >
void setSolid (SdfFn &&sdfFn)
 Build the cut-cell operators from an SDF callable sdfFn(worldPoint) (>0 fluid).
 
const std::vector< double > & velocity (int c) const
 
Index numLeaves () const
 
bool isFluid (Index i) const
 
bool isCut (Index i) const
 
Index numCfCutFaces () const
 The C/F census — see AmrFlow::numCfCutFaces (docs/amr_cf_flux_gate.md §6.5).
 
void beginAdapt ()
 
template<class SdfFn >
void finishAdapt (SdfFn &&sdfFn)
 
void step (int momSweeps=200, int presIters=60, int presSweeps=4)
 One Stokes projection step.
 
void project (int presIters=60, int presSweeps=4)
 Pressure projection of the current velocity in place: solve ∇²φ = ∇·u and correct u -= ∇φ.
 
double divergence (const std::array< std::vector< double >, 3 > &vel, Index i) const
 Openness-weighted FV divergence at leaf i, C/F-consistent: sum over (sub)faces of α·area·(outward face velocity), face velocity = ½(u_i+u_j); /V_i.
 
double divNormL2 (const std::array< std::vector< double >, 3 > &vel) const
 
double divNormL2Regular (const std::array< std::vector< double >, 3 > &vel) const
 divNormL2 restricted to REGULAR fluid rows (fluid and not cut) — the companion of divNormFaceRegular below; the two are compared on the band=0 mesh.
 
double divNormFaceRegular () const
 ‖D_std(uf)‖₂ over REGULAR fluid rows only.
 
std::pair< double, double > cfFluxIdentity () const
 Rule (I) of docs/amr_cf_flux_gate.md §4, measured (§6.6): the advecting face field's C/F delta and the divergence constraint's C/F delta must be THE SAME correction, so that D_std(Δuf) ≡ Δ_cfDiv entry by entry — which is what makes uf a conservative flux in the presence of the quadratic C/F scheme (L = D_std·Gf inverts only what rhs = D_std·F(u*) put in).
 
std::array< std::vector< double >, 3 > & velocityRef ()
 
void buildFaceField ()
 Build the ABC/Basilisk divergence-free FACE field from the current cell velocity u* and the projection potential φ: uf_f = ½(u*_i+u*_j) − (φ₊−φ₋)/d_f, the +axis face velocity.
 
double divNormFace () const
 L2 norm of the divergence of the FACE field uf_ (the div-free flux).
 
const std::vector< double > & faceField () const
 The divergence-free face field (read-only): uf[faceStart()[i]+s] for cell i's s-th forEachFaceFull face.
 
const std::vector< Index > & faceStart () const
 

Detailed Description

template<unsigned Bits = 21u>
class peclet::amr::oracle::AmrFlow< Bits >

Definition at line 60 of file flow_oracle.hpp.

Member Typedef Documentation

◆ Octree

template<unsigned Bits = 21u>
using peclet::amr::oracle::AmrFlow< Bits >::Octree = BlockOctree<3, Bits>

Definition at line 62 of file flow_oracle.hpp.

Member Function Documentation

◆ init() [1/2]

template<unsigned Bits = 21u>
void peclet::amr::oracle::AmrFlow< Bits >::init ( const Octree &  t,
Real  h0,
Vec< 3 >  origin = Vec<3>{} 
)
inline

Definition at line 64 of file flow_oracle.hpp.

◆ init() [2/2]

template<unsigned Bits = 21u>
void peclet::amr::oracle::AmrFlow< Bits >::init ( const Octree &  t,
const Vec< 3 > &  h0,
Vec< 3 >  origin = Vec<3>{} 
)
inline

Definition at line 67 of file flow_oracle.hpp.

◆ setDensity()

template<unsigned Bits = 21u>
void peclet::amr::oracle::AmrFlow< Bits >::setDensity ( double  rho)
inline

Definition at line 73 of file flow_oracle.hpp.

References peclet::amr::transferFieldGradients().

◆ setViscosity()

template<unsigned Bits = 21u>
void peclet::amr::oracle::AmrFlow< Bits >::setViscosity ( double  mu)
inline

Definition at line 74 of file flow_oracle.hpp.

◆ setDt()

template<unsigned Bits = 21u>
void peclet::amr::oracle::AmrFlow< Bits >::setDt ( double  dt)
inline

Definition at line 75 of file flow_oracle.hpp.

References peclet::amr::transferFieldGradients().

◆ setBodyForce()

template<unsigned Bits = 21u>
void peclet::amr::oracle::AmrFlow< Bits >::setBodyForce ( double  fx,
double  fy,
double  fz 
)
inline

Definition at line 76 of file flow_oracle.hpp.

References peclet::amr::transferFieldGradients().

◆ setAdvection()

template<unsigned Bits = 21u>
void peclet::amr::oracle::AmrFlow< Bits >::setAdvection ( bool  on)
inline

Definition at line 77 of file flow_oracle.hpp.

◆ setAdvectionScheme()

template<unsigned Bits = 21u>
void peclet::amr::oracle::AmrFlow< Bits >::setAdvectionScheme ( int  s)
inline

High-order advection scheme: 0 = second-order upwind (SOU, default), 1 = Koren TVD.

Definition at line 79 of file flow_oracle.hpp.

References peclet::amr::transferFieldGradients().

◆ setImplicitAdvection()

template<unsigned Bits = 21u>
void peclet::amr::oracle::AmrFlow< Bits >::setImplicitAdvection ( bool  on)
inline

Implicit-FOU deferred-correction advection (default ON): the first-order-upwind part is solved implicitly (in the momentum operator) and the high-order − FOU difference is explicit — unconditionally stable for advection.

OFF ⇒ fully explicit high-order advection.

Definition at line 84 of file flow_oracle.hpp.

◆ setGhostGradient()

template<unsigned Bits = 21u>
void peclet::amr::oracle::AmrFlow< Bits >::setGhostGradient ( bool  on)
inline

Directional ghost cell-gradient for the −∇pⁿ predictor and the projection's cell correction (the AMR analog of flow's collocated set_face_interp(9) hybrid): on cells with a solid-centered axis neighbour, gradOf reads the DECOUPLED p=0 of that neighbour through partially-open faces — a gauge-dependent O(1/h) gradient error at cut cells (measured in tests/study_amr_ghost_apriori.cpp).

The directional gradient is central where both axis neighbours are fluid-centered and 2nd-order one-sided toward the fluid else — O(h²) and gauge-exact. The aperture projection (divergence + φ solve + face field) is UNCHANGED, so this stays throat-safe. Default OFF (bit-identical legacy path). Call before setSolid.

Definition at line 93 of file flow_oracle.hpp.

◆ setApertureOrder()

template<unsigned Bits = 21u>
void peclet::amr::oracle::AmrFlow< Bits >::setApertureOrder ( int  order)
inline

FULL directional ghost-cell projection (the AMR port of flow's collocated set_ghost_projection): the pressure system becomes rho·(L_bin + Delta) phi = rho·D_g(u*) — the BINARY-openness FV Laplacian (preconditioned by the unchanged openness MG) plus the wall-anchored closure overlay on the finest-band rows, solved by MG-preconditioned BiCGStab; the constraint is the ghost-closed divergence of the ½/½ face-averaged field.

Implies setGhostGradient (the predictor/correction gradient). (matrixOrder, rhsOrder) = closure orders for the implicit matrix vs the RHS divergence; (1, 2) is the validated flow default (2nd-order steady constraint on a 7-point near-symmetric matrix). Default OFF. Call before setSolid. QUARANTINED (2026-08-19, mirrors the device AmrFlow): DEFAULT OFF everywhere — the aperture projection is the production path for Stokes AND NS (the former NS AUTO-arm was retired with the aperture-PCG-under-advection fix; see docs/amr_aperture_advection_plan.md §RESOLVED). Engages only on an explicit setGhostProjection(true). Call before setSolid. Aperture estimator order for the (fallback) aperture projection: 2 = analytic marching-squares (DEFAULT since 2026-08-26), 1 = legacy one-sample model. Before setSolid.

Definition at line 109 of file flow_oracle.hpp.

References peclet::amr::transferFieldGradients().

◆ setGhostProjection()

template<unsigned Bits = 21u>
void peclet::amr::oracle::AmrFlow< Bits >::setGhostProjection ( bool  on,
int  matrixOrder = 2,
int  rhsOrder = 2 
)
inline

Definition at line 110 of file flow_oracle.hpp.

References peclet::amr::transferFieldGradients().

◆ setGhostSampled()

template<unsigned Bits = 21u>
void peclet::amr::oracle::AmrFlow< Bits >::setGhostSampled ( bool  on)
inline

SAMPLED ghost projection: the mixed-level cut-band prototype (the D1 machinery of docs/amr_mixed_level_cut_band_plan.md — cut cells at MULTIPLE octree levels, chain entries across 2:1 boundaries replaced by degree-2 LS virtual samples).

Implies setGhostProjection (call it too, with the closure orders); replaces the finest-band contract (no band throw) and the openness rule by the level-aware canonical form (makeBinaryOpenFnMixed). Host-oracle only. Call before setSolid.

Definition at line 121 of file flow_oracle.hpp.

◆ setCfScheme()

template<unsigned Bits = 21u>
void peclet::amr::oracle::AmrFlow< Bits >::setCfScheme ( int  scheme)
inline

Coarse/fine (2:1) interface scheme (cf_scheme.hpp): 0 = standard two-point flux (default, 1st-order at level boundaries, bit-identical legacy path), 1 = Martin–Cartwright tangential quadratic (2nd-order).

Applied to everything the STEADY solution feels: the momentum diffusion (as a lagged deferred-correction RHS term), the RHS divergence constraint, and the pressure gradients (predictor + cell correction). The pressure MATRIX / MG hierarchy stays on the standard consistent operator (the (1,2)-mixed philosophy: at the fixed point φ→0, the matrix C/F order does not move the steady solution). Call before setSolid.

Definition at line 129 of file flow_oracle.hpp.

References peclet::amr::transferFieldGradients().

◆ advectTerm()

template<unsigned Bits = 21u>
double peclet::amr::oracle::AmrFlow< Bits >::advectTerm ( int  comp,
Index  i 
) const
inline

Conservative Koren-TVD advection term ∇·(u u_comp) at leaf i (physical units; the explicit momentum advection).

Exposed for testing.

Definition at line 133 of file flow_oracle.hpp.

References peclet::amr::transferFieldGradients().

◆ setSolid()

◆ velocity()

template<unsigned Bits = 21u>
const std::vector< double > & peclet::amr::oracle::AmrFlow< Bits >::velocity ( int  c) const
inline

Definition at line 263 of file flow_oracle.hpp.

References peclet::amr::transferFieldGradients().

◆ numLeaves()

template<unsigned Bits = 21u>
Index peclet::amr::oracle::AmrFlow< Bits >::numLeaves ( ) const
inline

◆ isFluid()

template<unsigned Bits = 21u>
bool peclet::amr::oracle::AmrFlow< Bits >::isFluid ( Index  i) const
inline

Definition at line 265 of file flow_oracle.hpp.

References peclet::amr::transferFieldGradients().

◆ isCut()

template<unsigned Bits = 21u>
bool peclet::amr::oracle::AmrFlow< Bits >::isCut ( Index  i) const
inline

Definition at line 266 of file flow_oracle.hpp.

References peclet::amr::transferFieldGradients().

◆ numCfCutFaces()

template<unsigned Bits = 21u>
Index peclet::amr::oracle::AmrFlow< Bits >::numCfCutFaces ( ) const
inline

The C/F census — see AmrFlow::numCfCutFaces (docs/amr_cf_flux_gate.md §6.5).

Definition at line 268 of file flow_oracle.hpp.

◆ beginAdapt()

template<unsigned Bits = 21u>
void peclet::amr::oracle::AmrFlow< Bits >::beginAdapt ( )
inline

Definition at line 271 of file flow_oracle.hpp.

◆ finishAdapt()

◆ step()

template<unsigned Bits = 21u>
void peclet::amr::oracle::AmrFlow< Bits >::step ( int  momSweeps = 200,
int  presIters = 60,
int  presSweeps = 4 
)
inline

One Stokes projection step.

momSweeps Gauss-Seidel sweeps per momentum component; presIters×presSweeps for the pressure solve.

Definition at line 298 of file flow_oracle.hpp.

References peclet::amr::cfApplyHost(), peclet::amr::BlockOctree< Dim, Bits >::numLeaves(), peclet::amr::oracle::AmrFlow< Bits >::project(), peclet::amr::standard, peclet::amr::CfCsr::start, and peclet::amr::transferFieldGradients().

◆ project()

template<unsigned Bits = 21u>
void peclet::amr::oracle::AmrFlow< Bits >::project ( int  presIters = 60,
int  presSweeps = 4 
)
inline

◆ divergence()

template<unsigned Bits = 21u>
double peclet::amr::oracle::AmrFlow< Bits >::divergence ( const std::array< std::vector< double >, 3 > &  vel,
Index  i 
) const
inline

Openness-weighted FV divergence at leaf i, C/F-consistent: sum over (sub)faces of α·area·(outward face velocity), face velocity = ½(u_i+u_j); /V_i.

Uses the same face enumeration as the pressure operator (forEachFaceFull).

Definition at line 406 of file flow_oracle.hpp.

References peclet::amr::AmrPoisson< Dim, Bits >::cellVolume(), peclet::amr::AmrPoisson< Dim, Bits >::forEachFaceFull(), and peclet::amr::transferFieldGradients().

Referenced by peclet::amr::oracle::AmrFlow< Bits >::divNormL2(), peclet::amr::oracle::AmrFlow< Bits >::divNormL2Regular(), and peclet::amr::oracle::AmrFlow< Bits >::project().

◆ divNormL2()

template<unsigned Bits = 21u>
double peclet::amr::oracle::AmrFlow< Bits >::divNormL2 ( const std::array< std::vector< double >, 3 > &  vel) const
inline

◆ divNormL2Regular()

template<unsigned Bits = 21u>
double peclet::amr::oracle::AmrFlow< Bits >::divNormL2Regular ( const std::array< std::vector< double >, 3 > &  vel) const
inline

divNormL2 restricted to REGULAR fluid rows (fluid and not cut) — the companion of divNormFaceRegular below; the two are compared on the band=0 mesh.

Definition at line 429 of file flow_oracle.hpp.

References peclet::amr::oracle::AmrFlow< Bits >::divergence(), peclet::amr::BlockOctree< Dim, Bits >::numLeaves(), and peclet::amr::transferFieldGradients().

◆ divNormFaceRegular()

template<unsigned Bits = 21u>
double peclet::amr::oracle::AmrFlow< Bits >::divNormFaceRegular ( ) const
inline

‖D_std(uf)‖₂ over REGULAR fluid rows only.

Cut rows are excluded ON PURPOSE: under the ghost scheme the constraint actually solved at a cut row is this divergence PLUS the closure overlay's delta, which is a functional of the CELL velocities and so cannot appear in any norm of uf — D_std(uf) ≠ 0 there BY DESIGN (see divNormFace, and docs/amr_cf_flux_gate.md §2 "out of scope"). On the REGULAR rows it is the solve residual, and it is exactly where the per-ROW C/F gate used to leave a non-decaying O(1) mass source: the regular cell across a cut-adjacent 2:1 face booked a C/F correction in its constraint that the cut cell did not, while uf carried it for both.

Definition at line 448 of file flow_oracle.hpp.

References peclet::amr::AmrPoisson< Dim, Bits >::cellVolume(), peclet::amr::AmrPoisson< Dim, Bits >::forEachFaceFull(), peclet::amr::BlockOctree< Dim, Bits >::numLeaves(), and peclet::amr::transferFieldGradients().

◆ cfFluxIdentity()

template<unsigned Bits = 21u>
std::pair< double, double > peclet::amr::oracle::AmrFlow< Bits >::cfFluxIdentity ( ) const
inline

Rule (I) of docs/amr_cf_flux_gate.md §4, measured (§6.6): the advecting face field's C/F delta and the divergence constraint's C/F delta must be THE SAME correction, so that D_std(Δuf) ≡ Δ_cfDiv entry by entry — which is what makes uf a conservative flux in the presence of the quadratic C/F scheme (L = D_std·Gf inverts only what rhs = D_std·F(u*) put in).

Returns {‖D_std(Δuf) − Δ_cfDiv‖₂, ‖Δ_cfDiv‖₂} evaluated on the CURRENT cell velocity. The first component is a permanent mass source when it is non-zero: it is proportional to the velocity, not to φ, so it does not decay at steady state. Measured 2.018e-01 on the band=0 mesh under the per-ROW gate, 8.7e-17 on a finest band (where no cut cell has a C/F face at all).

Definition at line 476 of file flow_oracle.hpp.

References peclet::amr::AmrPoisson< Dim, Bits >::cellVolume(), peclet::amr::cfApplyCompHost(), peclet::amr::AmrPoisson< Dim, Bits >::forEachFaceFull(), peclet::amr::BlockOctree< Dim, Bits >::numLeaves(), peclet::amr::CfCompCsr::start, peclet::amr::transferFieldGradients(), and peclet::amr::CfUfDelta::vel.

◆ velocityRef()

template<unsigned Bits = 21u>
std::array< std::vector< double >, 3 > & peclet::amr::oracle::AmrFlow< Bits >::velocityRef ( )
inline

Definition at line 501 of file flow_oracle.hpp.

◆ buildFaceField()

template<unsigned Bits = 21u>
void peclet::amr::oracle::AmrFlow< Bits >::buildFaceField ( )
inline

Build the ABC/Basilisk divergence-free FACE field from the current cell velocity u* and the projection potential φ: uf_f = ½(u*_i+u*_j) − (φ₊−φ₋)/d_f, the +axis face velocity.

Because the pressure operator is L = D·G_face with the SAME (sub)faces, this gives D(uf)=D u*−Lφ = 0 exactly (to the φ-solve residual). Call after the pressure solve, before the cell-gradient correction (so u_ still holds u*). C/F-consistent: a 2:1 sub-face uses (φ_fine−φ_coarse)/d at the fine area.

Definition at line 509 of file flow_oracle.hpp.

References peclet::amr::cfApplyCompHost(), peclet::amr::AmrPoisson< Dim, Bits >::forEachFaceFull(), peclet::amr::BlockOctree< Dim, Bits >::numLeaves(), peclet::amr::standard, peclet::amr::CfCompCsr::start, peclet::amr::transferFieldGradients(), and peclet::amr::CfUfDelta::vel.

Referenced by peclet::amr::oracle::AmrFlow< Bits >::project().

◆ divNormFace()

template<unsigned Bits = 21u>
double peclet::amr::oracle::AmrFlow< Bits >::divNormFace ( ) const
inline

L2 norm of the divergence of the FACE field uf_ (the div-free flux).

After buildFaceField this is the φ-solve residual (→ machine zero with a tight solve), vs the O(h²) residual of the cell field.

Definition at line 538 of file flow_oracle.hpp.

References peclet::amr::AmrPoisson< Dim, Bits >::cellVolume(), peclet::amr::AmrPoisson< Dim, Bits >::forEachFaceFull(), peclet::amr::BlockOctree< Dim, Bits >::numLeaves(), and peclet::amr::transferFieldGradients().

◆ faceField()

template<unsigned Bits = 21u>
const std::vector< double > & peclet::amr::oracle::AmrFlow< Bits >::faceField ( ) const
inline

The divergence-free face field (read-only): uf[faceStart()[i]+s] for cell i's s-th forEachFaceFull face.

Definition at line 557 of file flow_oracle.hpp.

◆ faceStart()

template<unsigned Bits = 21u>
const std::vector< Index > & peclet::amr::oracle::AmrFlow< Bits >::faceStart ( ) const
inline

Definition at line 558 of file flow_oracle.hpp.


The documentation for this class was generated from the following file: