API Reference

This section provides detailed documentation for the most common Python API functions and objects in Burbuja.

burbuja() Function

burbuja(structure, grid_resolution=0.1, use_cupy=False, use_float32=False, density_threshold=0.25, neighbor_cells=4)

Detect bubbles in a structure or trajectory and return a list of Bubble objects (one per frame).

Parameters:

• structure (str or mdtraj.Trajectory) – Path to a structure file (e.g., PDB, DCD) or an mdtraj.Trajectory object.

• grid_resolution (float) – Grid spacing in nanometers. Default: 0.1

• use_cupy (bool) – Use CuPy for GPU acceleration. Default: False

• use_float32 (bool) – Use float32 precision for calculations. Default: False

• density_threshold (float) – Density threshold for void detection (g/L). Default: 0.25

• neighbor_cells (int) – Number of cells from the central cell to include in the density average. Default: 4

Returns:

List of Bubble objects, one per frame.

Return type:

list[Bubble]

Example:

import mdtraj
from Burbuja import burbuja
traj = mdtraj.load('traj.dcd', top='top.prmtop')
bubbles = burbuja.burbuja(traj, grid_resolution=0.1, use_cupy=True)
for i, bubble in enumerate(bubbles):
         print(f"Frame {i}: Bubble volume = {bubble.total_bubble_volume:.3f} nm^3")

has_bubble() Function

has_bubble(structure, grid_resolution=0.1, use_cupy=False, dx_filename_base=None, density_threshold=0.25, minimum_bubble_fraction=0.005, neighbor_cells=4)

Quickly check if a structure or trajectory contains a significant bubble.

Parameters:

• structure (str or mdtraj.Trajectory) – Path to a structure file or an mdtraj.Trajectory object.

• grid_resolution (float) – Grid spacing in nanometers. Default: 0.1

• use_cupy (bool) – Use CuPy for GPU acceleration. Default: False

• dx_filename_base (str or None) – If provided, write DX files for each frame with a bubble. Default: None

• density_threshold (float) – Density threshold for void detection (g/L). Default: 0.25

• minimum_bubble_fraction (float) – Minimum fraction of system volume for a bubble to be considered significant. Default: 0.005

• neighbor_cells (int) – Number of cells from the central cell to include in the density average. Default: 4

Returns:

True if a significant bubble is found, False otherwise.

Return type:

bool

Example:

from Burbuja import burbuja
import mdtraj
traj = mdtraj.load('traj.dcd', top='top.prmtop')
contains_bubble = burbuja.has_bubble(traj, use_cupy=True, dx_filename_base='bubble_output')
print("Contains bubble?", contains_bubble)

Bubble Object

The Bubble object represents a detected bubble or void region in a frame. It is returned by the burbuja() function.

Attributes:

• densities: 3D NumPy array of grid cell densities.

• bubble_data: 3D NumPy array (bool) indicating which cells are part of a bubble.

• atoms: Dictionary of atom records for bubble visualization (PDB format), as an alternative to DX file.

• total_atoms: Number of grid cells identified as part of a bubble.

• total_bubble_volume: Total volume of the bubble (nm³).

• total_system_volume: Total volume of the system (nm³).

• dx_header: Header information for DX file output.

• density_threshold: Density threshold used for bubble detection.

Methods:

• find(...): Identify bubble regions in the grid (used internally).

• write_pdb(filename): Write bubble atoms to a PDB file for visualization.

• write_densities_dx(filename): Write the density grid to a DX file.

• write_bubble_dx(filename): Write the bubble mask to a DX file.

Example:

from Burbuja import burbuja
import mdtraj
traj = mdtraj.load('traj.dcd', top='top.prmtop')
bubbles = burbuja.burbuja(traj)
for i, bubble in enumerate(bubbles):
         print(f"Frame {i}: Bubble volume = {bubble.total_bubble_volume:.3f} nm^3")
         print(f"System volume: {bubble.total_system_volume:.3f} nm^3")
         bubble.write_pdb(f"bubble_frame_{i}.pdb")
         bubble.write_bubble_dx(f"bubble_frame_{i}.dx")

See the tutorials for more advanced usage and visualization examples.