Burbuja User Guide

Command-Line Usage

Burbuja can be used as a command-line tool for detecting bubbles, vapor pockets, and voids in explicit solvent molecular dynamics (MD) simulation structures and trajectories.

Note

There is also a Python API for more advanced usage; see the API documentation for details.

To run Burbuja from the command line:

burbuja STRUCTURE_FILE [options]

Required Argument

STRUCTURE_FILE

Path to the input structure or trajectory file (typically a PDB file). If a PDB file is provided, Burbuja uses a fast, memory-efficient procedure. For other formats, you must also provide a topology file with --topology.

Options

  • -t, --topology TOPOLOGY

    Path to a topology file (e.g., PRMTOP, PSF) for use with MDTraj. Required if STRUCTURE_FILE is not a PDB. If omitted, STRUCTURE_FILE is assumed to be a PDB.

  • -r, --grid_resolution GRID_RESOLUTION

    Grid resolution in nanometers for bubble detection. Default: 0.1 nm.

  • -c, --use_cupy

    Enable GPU acceleration using CuPy. Default: False (CPU only).

  • -d, --detailed_output

    Enable detailed output, including per-frame bubble volumes and DX files for visualization. Default: False.

  • -D, --density_threshold DENSITY_THRESHOLD

    Density threshold (g/L) for void detection. Cells with neighbor-averaged density below this are considered voids. Default: 0.25 g/L.

  • -m, --minimum_bubble_volume MINIMUM_BUBBLE_VOLUME

    Minimum volume of any contiguous bubble to be considered significant. Default: 0.005.

  • -n, --neighbor_cells NEIGHBOR_CELLS

    Number of cells from the central cell to include in the density average (neighbor search radius). Default: 4.

  • -M, --mass_of_particles

    Assign an equal mass (in Daltons) to all particles. This could be helpful in situations where system particles don’t correspond to real elements, and thus masses aren’t known, such as a coarse-grain system. If left at the default of None, an automated attempt is made to guess particle masses individually. Default: None.

Examples

Detect bubbles in a PDB file (CPU):

burbuja mysystem.pdb

Detect bubbles in a trajectory with a topology file:

burbuja traj.dcd -t top.prmtop

Use a custom grid resolution and enable GPU acceleration:

burbuja mysystem.pdb -r 0.05 -c

Set a custom density threshold and minimum bubble volume:

burbuja mysystem.pdb -D 0.2 -m 0.01

Enable detailed output (per-frame volumes and DX files):

burbuja mysystem.pdb -d

Notes

  • For large systems, PDB input is recommended for speed and memory efficiency.

  • If using a non-PDB format, you must provide a compatible topology file.

  • GPU acceleration requires CuPy to be installed and a compatible GPU.

  • DX files (if detailed output is enabled) can be visualized with molecular graphics programs such as VMD or PyMOL.

  • For a coarse-grained (CG) system, it is recommended to use the ‘-M’/’–mass_of_particles’ argument, which assigns all particles a constant mass, since MDTraj will not know what mass to assign to the fictional coarse-grained particles. A value of 100 Daltons is a good starting point for a CG system.

For more details, see the full documentation and API guide.