BEEP — Binding Energy Evaluation Platform

BEEP is a binding energy evaluation platform and database for molecules on interstellar ice-grain mantles. It automates the full computational pipeline, from structure sampling through geometry optimization, binding energy computation, and data extraction. It is build using a QCFractal (v0.63+) server as the computation backend.

Installation

BEEP requires Python 3.10+ and the QCFractal v0.63+ stack. The supported install path is to clone a qcfractal-0.64 conda environment and pip-install BEEP on top:

conda create --clone qcfractal-0.64 -p /path/to/envs/beep-0.13
/path/to/envs/beep-0.13/bin/pip install .

Pure pip install . also works in any environment that already has the QCFractal stack (qcportal, qcelemental, qcfractalcompute) available.

Direct dependencies declared in pyproject.toml: qcportal>=0.63, qcelemental, matplotlib, scipy, seaborn. numpy, pandas, pydantic, tqdm, and pyyaml come transitively through qcportal.

Note: To run computations you also need a running QCFractal server (v0.63+) with compute workers. See the QCFractal documentation for server setup.

Usage

All workflows are driven through a single CLI entry point with a JSON configuration file:

beep --config input.json

The JSON file must contain a "workflow" key that selects which workflow to run.

Discovering workflows and configuration options

List all available workflows:

beep --workflows

Dump the full JSON schema for any workflow (shows every field, its type, default value, and description):

beep --schema sampling

This is the easiest way to create a new configuration file — start from the schema and fill in the required fields.

Workflows

Workflow	Description
sampling	Generate binding site candidates via random molecular placement, RMSD filtering, and geometry optimization
be_hess	Submit binding energy and Hessian computations for optimized structures
extract	Extract binding energies, apply ZPVE corrections, and generate summary tables and plots
pre_exp	Compute pre-exponential factors from vibrational analysis over a temperature range
geom_benchmark	Benchmark DFT geometry optimizations and per-component force RMSD along the reference trajectory against high-level reference data
energy_benchmark	Benchmark DFT binding energies against high-level reference values (CBS extrapolation), with optional gCP correction
nm_sampling	Benchmark DFT gradients on ± normal-mode displacements against a high-level (CCSD(T)) reference, with per-band force-RMSE ranking

Each workflow has a corresponding example configuration in the examples/ directory:

examples/
  sampling.json
  be_hess.json
  extract.json
  pre_exp.json
  geom_benchmark.json
  energy_benchmark.json

Output

Each workflow creates an organized output directory under the molecule name:

N2/
  sampling/       # binding site structures, site_finder debug data, log
  be_hess/        # log, config copy
  extract/        # CSV tables, SVG plots, log

Output folders contain a log file and a copy of the input configuration for reproducibility.

Tutorials

The tutorial/ directory contains Jupyter notebooks for:

• Data query — how to query the BEEP database using QCPortal
• Data generation — step-by-step walkthrough of the full BEEP protocol

Running tests

pip install .[test]
pytest

Have fun BEEPing!

Copyright

Copyright (c) 2022, Stefan Vogt-Geisse, Giulia M. Bovolenta

Acknowledgements

Project based on the Computational Molecular Science Python Cookiecutter version 1.6.