Jumping Bubbles

A high-performance computational framework for studying bubble coalescence and jumping phenomena on substrates using Basilisk C. This repository provides a complete suite of simulation tools, post-processing utilities, and validated test cases for investigating two-phase free-surface flows with adaptive mesh refinement.

Key Features

Advanced Two-Phase Flow Modeling

Volume of Fluid (VOF) method for sharp interface tracking
Conservative momentum advection coupled with VOF field
Accurate surface tension implementation using the Brackbill method
Reduced gravity approach for specific physical scenarios. This keeps the system of equations well-balanced.

High-Performance Computing

Adaptive octree mesh refinement based on multiple criteria:
- Interface fraction gradients
- Local curvature
- Velocity field variations
Parallel computation support:
- OpenMP for shared-memory systems
- MPI for distributed computing (HPC clusters)

Comprehensive Analysis Tools

Real-time monitoring of physical quantities
Advanced post-processing capabilities:
- 2D/3D visualization scripts
- Interface reconstruction
- Energy and momentum analysis
- Trajectory tracking

Project Structure

basilisk/src/ - # Core Basilisk C framework
- navier-stokes/ - # Flow solvers
  - centered.h - # Main centered NS solver
  - conserving.h - # Conservative form solver
- two-phase*.h - # Two-phase flow implementations
- vof.h - # Volume of Fluid method
- curvature.h - # Interface property calculations
- tension.h - # Surface tension (Brackbill)
- integral.h - # Surface tension integral form
- viscosity.h - # Implicit viscous stress solver
- axi.h - # Axisymmetric computations
src-local/ - # Project-specific modifications
postProcess/ - # Analysis and visualization
- Video2DSlice.py - # 2D slice animations
- Video3D.py - # 3D visualization
- Visualization3D.ipynb - # Interactive 3D notebook
- getFacets3D.c - # Interface extraction
simulationCases/ - # Validation cases
- JumpingBubbles.c - # Standard test case
- JumpingBubbles-hydrophilic.c - # Hydrophilic substrate
- runCases*.sh - # Execution scripts

Installation

Prerequisites

GCC compiler (version 7.0+)
MPI implementation (OpenMPI or MPICH)
Python 3.7+ (for post-processing)
Required Python packages: numpy, matplotlib, scipy
Xcode Command Line Tools (for MacOS users)

Setting up Basilisk

Clone this repository:

git clone https://github.com/comphy-lab/JumpingBubbles.git
cd JumpingBubbles

Run the installation script:
```
./reset_install_requirements.sh
```
This script will:
- Install Basilisk if not present (use --hard flag for fresh installation)
- Configure the environment automatically
- Create .project_config with required paths
- Verify the installation
Verify installation:
```
source .project_config
qcc --version
```

Usage

Running Simulations

Local Development (OpenMP)

# Compile
qcc -O2 -Wall -disable-dimensions -fopenmp -I$(PWD)/src-local testCases/JumpingBubbles.c -o JumpingBubbles -lm

# Run with 4 threads
export OMP_NUM_THREADS=4
./JumpingBubbles

HPC Deployment (MPI)

Generate initial condition locally first

Compile with MPI support:

CC99='mpicc -std=c99' qcc -Wall -O2 -D_MPI=1 -disable-dimensions \
-I$(PWD)/src-local testCases/JumpingBubbles.c -o JumpingBubbles -lm

Use provided Slurm script: testCases/runSnellius.sbatch

Post-Processing

Visualization

2D Slice Videos:

python postProcess/Video2DSlice.py <simulation_directory>

3D Visualization:

python postProcess/Video3D.py <simulation_directory>

Interactive Analysis:
- Open postProcess/Visualization3D.ipynb in Jupyter

Data Analysis

Use getFacets3D.c to extract interface geometry
Various slice extraction tools available in postProcess/

Contributing

We welcome contributions to improve Jumping Bubbles! Here’s how you can help:

Reporting Issues

Click on the “Issues” tab above or use these quick links: - Report a Bug - Request a Feature - Ask a Question - Open a Blank Issue

Making Changes

Fork the repository
Create a feature branch (git checkout -b feature/AmazingFeature)
Make your changes
Run tests and ensure they pass
Update documentation if needed
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Please ensure your PR: - Clearly describes the changes - Includes any relevant tests - Updates documentation as needed - References any related issues

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Citation

If you use this code in your research, please cite:

@software{jumping_bubbles_2024,
  author       = {Sanjay, V. and Yang, R.},
  title        = {Jumping Bubbles: A Computational Framework for Studying Bubble Coalescence},
  year         = {2025},
  publisher    = {Zenodo},
  version      = {v2.0},
  doi          = {10.5281/zenodo.14602623},
  url          = {https://comphy-lab.org/JumpingBubbles/}
}