Metadata-Version: 2.4
Name: mbe-tools
Version: 0.5.0
Summary: A practical toolkit for Many-Body Expansion (MBE) workflows: cluster design, MBE input generation, output parsing, and analysis.
Author: Jiarui Wang
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: analysis
Requires-Dist: matplotlib>=3.8; extra == 'analysis'
Requires-Dist: openpyxl>=3.1; extra == 'analysis'
Requires-Dist: pandas>=2.0; extra == 'analysis'
Provides-Extra: cli
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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.0 release**. License: **MIT**.

## Quick Start

### 1. Install

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

For development checks, install the test tools too:

```bash
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.

```bash
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:

```text
synthetic CLI workflow ok
```

The example contract is recorded in
[examples/synthetic/manifest.json](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.

```bash
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.

```toml
[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:

```bash
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. Read Next

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