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

├── .github/ - documentation site assets, build scripts, and workflows
├── .project_config.example - example Basilisk environment configuration
├── AGENTS.md - authoritative project instructions for coding agents
├── README.md - project overview and workflow documentation
├── default.params - example single-case runtime parameters
├── runParameterSweep.sh - deterministic sweep generator and dispatcher
├── runSimulation.sh - single-case compile/run entry point
├── runSweepSnellius.sbatch - Snellius wrapper around the shared MPI main-phase sweep runner
├── simulationCases/ - Basilisk entry points and preserved legacy sources
│   ├── JumpingDrops_Snellius_legacy.c - preserved legacy HPC variant
│   ├── JumpingDrops_legacy.c - preserved monolithic legacy source
│   ├── jumpingDrops_init.c - STL-to-dumpInit initialization phase
│   └── jumpingDrops_main.c - MPI-compatible main simulation phase
├── src-local/ - shared headers and parameter parsing helpers
│   ├── jumpingDrops_common.h - shared Basilisk constants, AMR logic, and events
│   ├── params.h - typed runtime accessors for C entry points
│   ├── parse_params.h - low-level C parser for key=value files
│   └── parse_params.sh - shared shell parser/update helpers
└── sweep.params - example sweep definition

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.