CLS-VoF lacks 3D support (integral.h surface tension + two-phase-clsvof.h)

[VatsalSy]

Summary

The CLS-VoF (Coupled Level-Set Volume-of-Fluid) implementation in Basilisk does not support true 3D simulations. While the code may compile with 3D grids (grid/octree.h), it contains hardcoded 2D implementations that produce incorrect results in 3D.

Critical Issue: The surface tension implementation (integral.h) lacks 3D formulations for curvature calculation and stress tensor computation, making CLS-VoF fundamentally incompatible with 3D flows.

🔴 Three Specific Bugs

1. integral.h: 2D-Only Curvature Calculation (Lines 98-107)

The distance_curvature() function only computes derivatives in x and y:

static inline double distance_curvature (Point point, scalar d)
{
  double dx = (d[1] - d[-1])/2.;              // x derivative only
  double dy = (d[0,1] - d[0,-1])/2.;          // y derivative only
  // Missing: dz, dzz, dxz, dyz for 3D
  double dn = sqrt(sq(dx) + sq(dy)) + 1e-30;  // 2D gradient only
  return (sq(dx)*dyy - 2.*dx*dy*dxy + sq(dy)*dxx)/cube(dn)/Delta;
}

Missing for 3D: z-direction derivatives and 3D mean curvature formula.

2. integral.h: 2×2 Stress Tensor Instead of 3×3 (Lines 146-147)

scalar Sxx[], Sxy[], Syy[], Syx[];
tensor S; S.x.x = Sxx, S.x.y = Sxy, S.y.y = Syy, S.y.x = Syx;

Missing for 3D: Sxz, Syz, Szz components needed for full 3D stress tensor.

3. two-phase-clsvof.h: 4-Vertex Averaging Instead of 8 (Line 37)

event init (i = 0)
{
  vertex scalar phi[];
  foreach_vertex()
    phi[] = (d[] + d[-1] + d[0,-1] + d[-1,-1])/4.;  // Only 4 vertices (2D)
  fractions (phi, f);
}

Required for 3D: Average over all 8 vertices of a cube.

📊 Evidence

Test Cases Are 2D/Axisymmetric Only

• test/rising.c → 2D or axisymmetric
• test/capwave.c → 2D
• test/marangoni.c → Axisymmetric
• No 3D test cases exist for CLS-VoF

User Evidence

File: basilisk-wiki/sandbox/farsoiya/marangoni_surfactant/3D_rising_bubble.c

#include "grid/octree.h"              // 3D grid
#include "two-phase.h"                // Using standard VOF
// #include "two-phase-clsvof.h"      // CLS-VoF commented out for 3D!

Users have encountered this limitation and switched to standard VOF for 3D.

💥 Impact

Current Status:

• ✅ Works perfectly in 2D Cartesian
• ✅ Works perfectly in axisymmetric
• ❌ Produces incorrect results in 3D:
  • Wrong initial interface
  • Incorrect surface tension forces
  • Missing z-direction stress components

Affected Use Cases:

• 3D rising/falling bubbles and droplets
• 3D capillary-driven flows
• Any 3D surface tension-dominated flow
• Users trying to leverage CLS-VoF's superior curvature accuracy in 3D

✅ Current Workaround

For 3D two-phase flows, use standard VOF:

#include "grid/octree.h"
#include "two-phase.h"      // Standard VOF (not CLS-VoF)
#include "tension.h"        // Height-function curvature

📋 Detailed Technical Report

A comprehensive analysis is available in: CLS-VOF_3D-missing.md

This report includes:

• Detailed code analysis with line numbers
• Required changes for 3D support
• Technical requirements for implementation
• Testing recommendations

🔧 Suggested Fix

The main blocker is integral.h (surface tension), not the CLS-VoF coupling itself. Required changes:

1. Extend curvature to 3D: Add z-derivatives and 3D mean curvature formula
2. Extend stress tensor to 3×3: Add Sxz, Syz, Szz components
3. Extend stencils: Update to handle 3D neighbors
4. Fix initialization: Use 8-vertex averaging for 3D

🎯 Priority

This is a significant limitation because:

• CLS-VoF is advertised as a superior method for surface tension
• Users expect it to work in 3D (code compiles without warnings)
• Silent failure produces incorrect results
• Many modern CFD applications require 3D simulations

🏷️ Labels

• bug: Current behavior is incorrect in 3D
• enhancement: Adding 3D support would be a valuable feature

---

Reported by: Comphy Lab team
Repository: comphy-lab/basilisk-C (fork of basilisk.fr)
Basilisk Version: Current main branch (synced with basilisk.fr)