KBKit: Kirkwood-Buff Analysis Toolkit¶
Check out our latest release on GitHub!
API Reference:
Installation¶
Quick install via PyPI:
pip install kbkit
Developer install (recommended for contributors or conda users):
Clone the GitHub repository and use the provided Makefile to set up your development environment:
git clone https://github.com/anl-sepsci/kbkit.git
cd kbkit
make setup-dev
This one-liner creates the kbkit-dev conda environment, installs kbkit in editable mode, and runs the test suite.
To install without running tests:
make dev-install
To build and install the package into a clean user environment:
make setup-user
For a full list of available commands:
make help
File Organization¶
For running kbkit.core.pipeline.Pipeline or its dependencies, the following file structure is required: a structured directory layout that separates mixed systems from pure components. This organization enables automated parsing, reproducible KB integrals, and scalable analysis across chemical systems.
NOTE: KBKit currently only supports parsing for GROMACS files.
An example of file organization:
kbi_dir/
├── project/
│ └── system/
│ ├── rdf_dir/
│ │ ├── mol1_mol1.xvg
│ │ ├── mol1_mol2.xvg
│ │ └── mol1_mol2.xvg
│ ├── system_npt.edr
│ ├── system_npt.gro
│ └── system.top
└── pure_components/
└── molecule1/
├── molecule1_npt.edr
└── molecule1.top
Requirements:
- Each system to be analyzed must include:
rdf_dir/ containing .xvg RDF files for all pairwise interactions
either .top topology file or .gro structure file (.gro is recommended)
.edr energy file
- Each pure component must include:
either .top topology file or .gro structure file (.gro is recommended)
.edr energy file
all other files (optional)
These inputs are parsed by kbkit.parsers and fed into kbkit.analysis for Kirkwood-Buff integrals and thermodynamic predictions. The layout is designed for:
Discoverability: Clear separation of mixed vs. pure systems
Reproducibility: Consistent file naming and structure
Extensibility: Easy to add new molecules or systems
For contributors, this structure ensures semantic clarity and minimizes onboarding friction. New systems can be added by replicating the folder pattern and updating input paths—no need to modify core logic.