mbe-tools 0.5.1rc1

A practical toolkit for Many-Body Expansion (MBE) workflows: cluster design, MBE input generation, output parsing, and analysis.

mbe-tools

mbe-tools is a Python command-line toolkit for Many-Body Expansion (MBE) workflows: fragment a cluster, prepare Q-Chem/ORCA/Molpro jobs, parse outputs, and assemble MBE energies or project-mode derivative properties.

Status: 0.5.1rc1 release. License: MIT.

Quick Start

1. Install

cd mbe-tools
python3 -m pip install -e ".[analysis,cli]"
mbe --help

For development checks, install the test tools too:

python3 -m pip install -e ".[analysis,cli,dev]"

2. Run The Built-In Smoke Test

The synthetic example uses small committed Q-Chem-like and ORCA-like outputs, so it does not require external quantum-chemistry software.

python3 examples/synthetic/regenerate.py --check
python3 examples/synthetic/check_cli_workflow.py

The workflow smoke runs parse, validate, info, calc, and analyze. Success ends with:

synthetic CLI workflow ok

The example contract is recorded in examples/synthetic/manifest.json.

3. Direct Workflow In Five Commands

Use this when you want explicit control over each stage and do not need a central project file.

mbe fragment water7.xyz --out-xyz sampled.xyz --n 7 --seed 1
mbe gen water7.xyz --max-order 2 --backend orca --no-cp --out-dir geoms
mbe build-input geoms --glob "*.geom" --backend orca --method HF --basis STO-3G --out-dir inputs
mbe parse outputs --program auto --glob-pattern "*.out" --out parsed.jsonl
mbe calc parsed.jsonl --scheme strict --to 2

Typical direct stages are:

Stage	Command	Output
Fragment or sample	mbe fragment	sampled .xyz
Generate subsets	mbe gen or mbe gen-from-monomer	.geom files
Render inputs	mbe build-input	.inp files and optional sidecars
Parse outputs	mbe parse	parsed.jsonl
Inspect and assemble	mbe validate, mbe info, mbe calc, mbe analyze	summaries, CSV, plots

4. Project Workflow In One mbe.toml

Use this when you want one project file to plan jobs, write inputs, parse outputs, and assemble results. Project mode does not write intermediate .geom files.

[project]
name = "water7"
source_xyz = "water7.xyz"

[fragmentation]
scheme = "gmbe"      # mbe, screened_mbe, or gmbe
max_order = 1        # centered GMBE neighborhoods
cp = false

[fragmentation.gmbe]
cutoff_angstrom = 2.0
distance_metric = "closest_atom"

[software]
backend = "orca"
method = "HF"
basis = "STO-3G"
charge = 0
multiplicity = 1
orca_maxcore = 3000
orca_nprocs = 8
tole = 8
thresh = 14
orca_hessian_keyword = "AnFreq"  # omit for ORCA NumFreq default

[task]
type = "hessian"     # energy, gradient, or hessian

[paths]
inputs_dir = "inputs"
outputs_dir = "outputs"
manifest = "jobs.manifest.json"
parsed_jsonl = "parsed.jsonl"
array_dir = "arrays"
result_dir = "results"

Run the stages:

mbe project --config mbe.toml --stage plan
mbe project --config mbe.toml --stage inputs
# run the external Q-Chem or ORCA jobs yourself
mbe project --config mbe.toml --stage parse
mbe project --config mbe.toml --stage assemble
mbe calc --hessian-matrix results/hessian_mbe.npy --xyz water7.xyz --freq-out results/frequencies.csv

5. ORCA CP Finite-Difference Hessian Sample

ORCA BSSEGradient.cmp produces CP-corrected gradients, not a direct CP Hessian. The bundled CP sample therefore writes a reference job plus paired +h/-h compound-gradient jobs, then expects the Hessian to be assembled from the final *_cp.engrad files.

python3 examples/orca_water_dimer_mbe2_cp_hessian/generate_cp_fd_inputs.py --nprocs 8 --maxcore-mb 2000

For this sample, --nprocs becomes %Pal nprocs inside the bundled BSSEGradient.cmp, and --maxcore-mb becomes ORCA %Maxcore in MB per process/core. The generated inputs keep those values explicit as compound variables:

nprocs = 8;
maxcore = 2000;

Project-mode [software].orca_nprocs and orca_maxcore still control normal ORCA inputs rendered by mbe project or mbe build-input; the CP sample uses its generator arguments because the resources must pass through %Compound.

6. Read Next

• User manual: manual/README.md
• Project workflow and mbe.toml: manual/04-project-workflow.md
• Python API reference: docs/API_REFERENCE.md
• Architecture note: docs/ARCHITECTURE.md
• Contract index: docs/contract_index.json