Menu

Jumping Drops

Jumping Drops is a Basilisk two-phase drop-impact workflow split into two entry points:

  • simulationCases/jumpingDrops_init.c creates dumpInit from STL geometry in serial.
  • simulationCases/jumpingDrops_main.c restores dump/dumpInit and runs the MPI-ready main simulation.

The standardized runtime contract is case.params: shell scripts generate and validate parameter files, and the Basilisk executables read the same file directly at runtime.

Requirements

  • Basilisk with qcc available on PATH
  • MPI tools (mpicc, mpirun, srun) for parallel main runs
  • A local .project_config file

Setup the local Basilisk path by copying and editing the example if needed:

cp .project_config.example .project_config
source .project_config

The vendored basilisk/ directory is treated as a local dependency and is ignored by git.

Quick Start

# Full workflow for one case
./runSimulation.sh default.params

# Initialization only
./runSimulation.sh --init-only default.params

# Main phase only with MPI
./runSimulation.sh --main-only --mpi --cores 8 default.params

# Deterministic parameter sweep
./runParameterSweep.sh sweep.params

# Inspect generated sweep cases without running them
./runParameterSweep.sh --dry-run sweep.params

Runtime Parameters

Parameter files use key=value lines with optional # comments.

Required single-case keys:

  • CaseNo
  • Oh
  • Bo
  • MAXlevel
  • tmax

The shared parser layers are:

  • src-local/parse_params.sh for shell runners and sweep generation
  • src-local/parse_params.h for low-level C parsing
  • src-local/params.h for typed C accessors with defaults and warnings

runSimulation.sh copies the chosen input file into simulationCases/<CaseNo>/case.params, then runs the compiled executable as:

./jumpingDrops_init case.params
./jumpingDrops_main case.params

Sweep files define:

  • BASE_CONFIG
  • CASE_START
  • CASE_END
  • one or more SWEEP_* variables

runParameterSweep.sh generates one case.params file per combination, enforces exact agreement between the generated combination count and the CASE_START/CASE_END range, and then dispatches each case through runSimulation.sh.

HPC Workflow

runSweepSnellius.sbatch is the main-only HPC runner. The expected workflow is:

  1. Generate dumpInit locally with ./runSimulation.sh --init-only ...
  2. Transfer dumpInit into each simulationCases/<CaseNo>/ directory on HPC
  3. Submit runSweepSnellius.sbatch

On Snellius, the batch script delegates to the shared root sweep runner in main-only MPI mode:

bash runParameterSweep.sh --skip-init --mpi --cores "${SLURM_NTASKS}" sweep.params

It sets MPI_LAUNCHER=srun and MPI_LAUNCHER_NFLAG=-n so the shared runSimulation.sh runner launches the main executable with srun instead of duplicating a separate HPC-only execution path.

Repository Structure

At runtime, new case directories are created under simulationCases/<CaseNo>/. These directories typically contain case.params, dumpInit, dump, log, and intermediate/snapshot-* outputs.

Notes

  • STL geometry is only used in the initialization phase; do not enable MPI there.
  • The main phase restores from dump, so dumpInit is copied to dump after a fresh init run.
  • CLAUDE.md is intentionally a one-line pointer to AGENTS.md and is ignored by git.

Generated Documentation

Root Directory

simulationCases

src-local