burbuja 1.0.3

Bubble detection for molecular dynamics simulations.

Burbuja

Overview

Detect bubbles, vapor pockets, and local voids within the explicit solvent of molecular dynamics (MD) simulation structures/trajectories.

The Burbuja (The Spanish word for 'bubble') program automates the checking of a MD simulation input or output structure, or collection of structures, for bubbles. Bubbles can often arise in the preparation or running of a simulation if periodic box dimensions are incorrectly chosen, if high energies or temperatures are inadvertently sampled, if bad starting structures are assigned, or if faulty parameters exist in the system. These bubbles and voids can be found 'manually' by examining the structure with a molecular viewing program, but bubbles can be easily missed, manual checking can be tiresome, and small or oddly-shaped bubbles can sometimes be difficult to see. Burbuja can detect bubbles of just about any shape and significant size, within cubic, rectangular, or triclinic boxes containing an explicit solvent. Burbuja can also take a variety of input structure files, due to its reliance on the MDTraj (https://www.mdtraj.org) software for loading and definition of molecular structures.

Burbuja has also been designed to detect bubbles efficiently and quickly, and can optionally make use of the CuPy library for GPU acceleration. Burbuja has also been coded with an eye toward very large structures, such as entire viruses or very large proteins, in excess of hundreds of millions of atoms, in order to detect the presence of bubbles. Burbuja may be used as a command-line tool, or its functions accessed directly by means of its API.

This README is only a quickstart guide to get Burbuja up and running as soon as possible. To see more detailed instructions and tutorials, please see https://burbuja.readthedocs.io/en/latest or the docs/ subfolder.

Install

The easiest, quickest way to install Burbuja is to use Mamba. If you don't already have Mamba installed, Download the Miniforge install script and run.

curl -O https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh
bash Miniforge3-$(uname)-$(uname -m).sh

Once this has been done, set up a new environment:

mamba create -n BURBUJA python=3.11 --yes
mamba activate BURBUJA

If you wish to benefit from GPU acceleration, install CuPy. See the CuPy documentation (https://docs.cupy.dev/en/stable/install.html) for detailed installation instruction for your own system using PyPI, Conda, or from Source, but if you're in a hurry, the following command should work:

mamba install cupy

Next, simply install Burbuja. All remaining dependencies should be handled automatically:

pip install burbuja

Example

One may try out the example systems in the Burbuja/examples/ subdirectory. Within, there are two files, "trypsin_benzamidine_bubble.pdb" and "trypsin_benzamidine_no_bubble.pdb". Try running the following commands:

cd examples/
burbuja trypsin_benzamidine_no_bubble.pdb

Burbuja should indicate that no bubble was present in the structure. Next, try the structure that does contain a bubble:

cd examples/
burbuja trypsin_benzamidine_bubble.pdb

Important Options and Hints

• In general, Burbuja programs can be run with the '-h' argument to see all available options. Please see https://burbuja.readthedocs.io/en/latest for a detailed description of programs and options.

Authors and Contributors

The following people have contributed directly to the coding and validation efforts of Burbuja (listed an alphabetical order of last name). Thanks also to everyone who has helped or will help improve this project by providing feedback, bug reports, or other comments.

• Rommie Amaro (principal investigator)
• Abraham Muñiz Chicharro (developer)
• Lane Votapka (developer)

Citing Burbuja

If you use Burbuja, please cite the following paper:

• Muniz-Chicharro A, Votapka L, Amaro R. Detection of Gas Bubbles and Local Voids in Molecular Simulations using burbuja. ChemRxiv. 2025; doi:10.26434/chemrxiv-2025-rxpnd This content is a preprint and has not been peer-reviewed.

Copyright

Copyright (c) 2025, Abraham Muñiz Chicharro and Lane Votapka