peace-protomer 0.1.0__tar.gz

peace_protomer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Zheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

peace_protomer-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: peace-protomer
+Version: 0.1.0
+Summary: Protomer Enumerator & Automatic Calculator for Energies: an atomistic workflow for determining acid-base prototropic tautomer microstate populations
+Author-email: Jonathan Zheng <jonathan.zheng@tuwien.ac.at>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jonwzheng/PEACE
+Project-URL: Repository, https://github.com/jonwzheng/PEACE
+Project-URL: Issues, https://github.com/jonwzheng/PEACE/issues
+Keywords: cheminformatics,tautomer,protomer,zwitterion,pKa,solvation,rdkit,xtb
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: <3.15,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rdkit
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: pillow
+Requires-Dist: prism-pruner
+Requires-Dist: matplotlib
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# PEACE: Protomer Enumerator & Automatic Calculator for Energies
+
+![PEACE Logo](https://raw.githubusercontent.com/jonwzheng/PEACE/main/docs/static/header.svg)
+
+## Overview
+PEACE is a lightweight cheminformatics workflow for enumerating acid-base tautomers. It also includes a calculator function that orchestrates QM calculations for estimating the microstate populations in numerous solvent systems. 
+
+For more information, please read the manuscript (and cite, if using this work):
+> Zheng, J. W., & Heid, E. (2026). An Atomistic Workflow for Determining Acid-Base Prototropic Tautomer Microstate Populations. RSC Advances.
+
+## Installation
+1. Install from PyPI with `pip install peace-protomer`.
+2. If using free energy simulations, additionally install the appropriate QM software:
+  - If using `xtb`-based methods, install `gxtb` version 2.0.1 or greater into `bin` (or specify its location with `--xtb-executable`). 
+  - If using DFT, install ORCA 6.x and add this to `bin` (or specify its location with `--orca-executable`).
+  - If using AIMNet2, install it into the same Python environment as PEACE with `pip install "aimnet[ase]"`.
+
+As an alternative to step 1, you can install from source:
+```
+git clone git@github.com:jonwzheng/PEACE.git
+cd PEACE
+python -m venv peace_env
+source peace_env/bin/activate
+pip install -e ".[test]"
+pytest
+```
+
+Example run:
+`peace --smiles "NCC(=O)O" --solvation` (equivalently `python -m peace.main ...`)
+
+CLI commands can be displayed e.g. with:
+`peace --help`
+
+## Python API
+Everything available on the CLI can also be run from Python e.g. (`--charge-min` -> `charge_min`, `--solv-sp-calculator` -> `solv_sp_calculator`). You can check their defaults with `peace.cli_defaults()`. By default, the Python API does not write a CSV or display plots unless you pass `output_csv=...` or `no_plot=False`.
+
+```python
+import peace
+
+# Tautomer/protomer enumeration only (no QM)
+result = peace.enumerate_protomers("O=C(O)CN(CCN(CC(=O)O)CC(=O)O)CC(=O)O", charge_min=-4, charge_max=2)
+for charge, species in result.species_by_charge.items():
+    print(charge, sum(len(t.protomers) for t in species.tautomers.values()))
+
+# Solvation free energies and Boltzmann populations
+result = peace.solvate("NCC(=O)O", max_conformers=2, scratch_root="./solvation_results")
+print(result.dataframe[["protomer_smiles", "boltzmann_fraction"]])
+
+# Any CLI option combination, e.g. pKa
+result = peace.solvate("NCC(=O)O", charge_min=0, charge_max=1, pka=True)
+print(result.pka_dataframe)
+```
+
+## How it works:
+
+1. **Tautomer Enumeration** using RDKit.
+2. **Protomer Enumeration** by searching each tautomer for acid/base sites and sequentially (de)protonating all possible combinations (this searches for zwitterion forms).
+3. **(Optional) Microstate Population Estimation** using quantum-chemical calculations, G = E_gas + G_RRHO + dG_solv:
+   - **Screening**: KDG conformer -> implicit-solvation SP, gas-phase SP, and frequencies (RRHO) on the screening geometry.
+   - **Refinement** (screened-in protomers): MMFF94-ranked conformer ensemble -> implicit-solvent optimization -> implicit-solvation SP on that geometry -> gas-phase re-optimization and gas-phase SP -> frequencies on the gas-phase geometry. Pass `--no-gas-optimize` to skip the gas-phase re-optimization and evaluate the gas SP and frequencies at the implicit-solvent geometry.
+   It is planned that a machine learning model will be made available to speed this up.
+4. **Visualization** of all relevant tautomer-protomers based on their graph representations. 
+
+## Calculators
+Each stage of the free-energy workflow has its own calculator:
+
+| Stage | Flag | Default | Options |
+| --- | --- | --- | --- |
+| Gas-phase SP + gas-phase re-optimization | `--gas-calculator` | `gxtb` | `gxtb`, `gfn2`, `aimnet2`, `orca` |
+| Frequencies (RRHO) | `--freq-calculator` | `gfn2` | `gfn2`, `gxtb`, `orca` |
+| Implicit-solvent optimization | `--solv-opt-calculator` | `gfn2` (GFN2-xTB/ALPB) | `gfn2`, `aimnet2`, `orca` |
+| Implicit-solvation free energy | `--solv-sp-calculator` | `cpcmx` (CPCM-X) | `cpcmx`, `orca` |
+
+`--freq-calculator gxtb` computes the RRHO contribution with g-xTB instead of GFN2-xTB frequencies; it may be slightly more accurate but is about 2x slower.
+
+ORCA stages take arbitrary method keywords: `--orca-keywords` sets a default for every ORCA stage, and `--gas-orca-keywords`, `--freq-orca-keywords`, `--solv-opt-orca-keywords`, `--solv-sp-orca-keywords` override it per stage. PEACE adds the job type (`Opt`/`FREQ`) and the solvation model itself: `--solv-opt-orca-model` (`cpcm`, `smd`) and `--solv-sp-orca-model` (`cpcm`, `smd`, `cosmors`). See `python -m peace.main --help` for more runtime options.
+
+Example: r2SCAN-3c gas-phase energies and frequencies, keeping GFN2-xTB/ALPB optimization and CPCM-X solvation:
+```
+python -m peace.main --smiles "NCC(=O)O" --solvation \
+    --gas-calculator orca --freq-calculator orca --orca-keywords "r2SCAN-3c"
+```
+
+## pKa Prediction
+The free energies of tautomers, and their ensembles, can be used to estimate pKa values. It is currently quite inaccurate and should be considered work in progress, or at least a way of estimating which micro-reactions contribute to acidity. Work is ongoing.
+
+You can call this with the `--pka` flag as well as `--proton-energy` to estimate the proton free energy in solution.

peace_protomer-0.1.0/README.md

@@ -0,0 +1,87 @@
+# PEACE: Protomer Enumerator & Automatic Calculator for Energies
+
+![PEACE Logo](https://raw.githubusercontent.com/jonwzheng/PEACE/main/docs/static/header.svg)
+
+## Overview
+PEACE is a lightweight cheminformatics workflow for enumerating acid-base tautomers. It also includes a calculator function that orchestrates QM calculations for estimating the microstate populations in numerous solvent systems. 
+
+For more information, please read the manuscript (and cite, if using this work):
+> Zheng, J. W., & Heid, E. (2026). An Atomistic Workflow for Determining Acid-Base Prototropic Tautomer Microstate Populations. RSC Advances.
+
+## Installation
+1. Install from PyPI with `pip install peace-protomer`.
+2. If using free energy simulations, additionally install the appropriate QM software:
+  - If using `xtb`-based methods, install `gxtb` version 2.0.1 or greater into `bin` (or specify its location with `--xtb-executable`). 
+  - If using DFT, install ORCA 6.x and add this to `bin` (or specify its location with `--orca-executable`).
+  - If using AIMNet2, install it into the same Python environment as PEACE with `pip install "aimnet[ase]"`.
+
+As an alternative to step 1, you can install from source:
+```
+git clone git@github.com:jonwzheng/PEACE.git
+cd PEACE
+python -m venv peace_env
+source peace_env/bin/activate
+pip install -e ".[test]"
+pytest
+```
+
+Example run:
+`peace --smiles "NCC(=O)O" --solvation` (equivalently `python -m peace.main ...`)
+
+CLI commands can be displayed e.g. with:
+`peace --help`
+
+## Python API
+Everything available on the CLI can also be run from Python e.g. (`--charge-min` -> `charge_min`, `--solv-sp-calculator` -> `solv_sp_calculator`). You can check their defaults with `peace.cli_defaults()`. By default, the Python API does not write a CSV or display plots unless you pass `output_csv=...` or `no_plot=False`.
+
+```python
+import peace
+
+# Tautomer/protomer enumeration only (no QM)
+result = peace.enumerate_protomers("O=C(O)CN(CCN(CC(=O)O)CC(=O)O)CC(=O)O", charge_min=-4, charge_max=2)
+for charge, species in result.species_by_charge.items():
+    print(charge, sum(len(t.protomers) for t in species.tautomers.values()))
+
+# Solvation free energies and Boltzmann populations
+result = peace.solvate("NCC(=O)O", max_conformers=2, scratch_root="./solvation_results")
+print(result.dataframe[["protomer_smiles", "boltzmann_fraction"]])
+
+# Any CLI option combination, e.g. pKa
+result = peace.solvate("NCC(=O)O", charge_min=0, charge_max=1, pka=True)
+print(result.pka_dataframe)
+```
+
+## How it works:
+
+1. **Tautomer Enumeration** using RDKit.
+2. **Protomer Enumeration** by searching each tautomer for acid/base sites and sequentially (de)protonating all possible combinations (this searches for zwitterion forms).
+3. **(Optional) Microstate Population Estimation** using quantum-chemical calculations, G = E_gas + G_RRHO + dG_solv:
+   - **Screening**: KDG conformer -> implicit-solvation SP, gas-phase SP, and frequencies (RRHO) on the screening geometry.
+   - **Refinement** (screened-in protomers): MMFF94-ranked conformer ensemble -> implicit-solvent optimization -> implicit-solvation SP on that geometry -> gas-phase re-optimization and gas-phase SP -> frequencies on the gas-phase geometry. Pass `--no-gas-optimize` to skip the gas-phase re-optimization and evaluate the gas SP and frequencies at the implicit-solvent geometry.
+   It is planned that a machine learning model will be made available to speed this up.
+4. **Visualization** of all relevant tautomer-protomers based on their graph representations. 
+
+## Calculators
+Each stage of the free-energy workflow has its own calculator:
+
+| Stage | Flag | Default | Options |
+| --- | --- | --- | --- |
+| Gas-phase SP + gas-phase re-optimization | `--gas-calculator` | `gxtb` | `gxtb`, `gfn2`, `aimnet2`, `orca` |
+| Frequencies (RRHO) | `--freq-calculator` | `gfn2` | `gfn2`, `gxtb`, `orca` |
+| Implicit-solvent optimization | `--solv-opt-calculator` | `gfn2` (GFN2-xTB/ALPB) | `gfn2`, `aimnet2`, `orca` |
+| Implicit-solvation free energy | `--solv-sp-calculator` | `cpcmx` (CPCM-X) | `cpcmx`, `orca` |
+
+`--freq-calculator gxtb` computes the RRHO contribution with g-xTB instead of GFN2-xTB frequencies; it may be slightly more accurate but is about 2x slower.
+
+ORCA stages take arbitrary method keywords: `--orca-keywords` sets a default for every ORCA stage, and `--gas-orca-keywords`, `--freq-orca-keywords`, `--solv-opt-orca-keywords`, `--solv-sp-orca-keywords` override it per stage. PEACE adds the job type (`Opt`/`FREQ`) and the solvation model itself: `--solv-opt-orca-model` (`cpcm`, `smd`) and `--solv-sp-orca-model` (`cpcm`, `smd`, `cosmors`). See `python -m peace.main --help` for more runtime options.
+
+Example: r2SCAN-3c gas-phase energies and frequencies, keeping GFN2-xTB/ALPB optimization and CPCM-X solvation:
+```
+python -m peace.main --smiles "NCC(=O)O" --solvation \
+    --gas-calculator orca --freq-calculator orca --orca-keywords "r2SCAN-3c"
+```
+
+## pKa Prediction
+The free energies of tautomers, and their ensembles, can be used to estimate pKa values. It is currently quite inaccurate and should be considered work in progress, or at least a way of estimating which micro-reactions contribute to acidity. Work is ongoing.
+
+You can call this with the `--pka` flag as well as `--proton-energy` to estimate the proton free energy in solution.

peace_protomer-0.1.0/peace/__init__.py

@@ -0,0 +1,31 @@
+"""
+PEACE - Protomer Enumeration And Charge Engine
+A package for molecular protomer and tautomer enumeration.
+"""
+
+__version__ = "0.1.0"
+__all__ = [
+    "protomer",
+    "engine",
+    "common",
+    "main",
+    "solvation",
+    "pka",
+    "api",
+    "run",
+    "enumerate_protomers",
+    "solvate",
+    "cli_defaults",
+    "PeaceResult",
+]
+
+_API_NAMES = {"run", "enumerate_protomers", "solvate", "cli_defaults", "PeaceResult"}
+
+
+def __getattr__(name):
+    # Lazy so that `import peace` stays cheap and peace.main can import __version__.
+    if name in _API_NAMES:
+        from peace import api
+
+        return getattr(api, name)
+    raise AttributeError(f"module 'peace' has no attribute {name!r}")

peace_protomer-0.1.0/peace/api.py

@@ -0,0 +1,110 @@
+"""
+High-level Python API mirroring the PEACE command-line interface.
+
+Every CLI flag is available as a keyword argument named after its argparse
+destination, i.e. the flag with the leading dashes removed and remaining dashes
+replaced by underscores (``--charge-min`` -> ``charge_min``,
+``--solv-sp-calculator`` -> ``solv_sp_calculator``). Use ``cli_defaults()`` to
+list them.
+
+Example::
+
+    import peace
+
+    result = peace.solvate("NCC(=O)O", max_conformers=2)
+    print(result.dataframe[["protomer_smiles", "boltzmann_fraction"]])
+"""
+
+from __future__ import annotations
+
+from os import PathLike
+from typing import Any
+
+from peace.main import PeaceResult, _build_cli_parser, run_from_args
+
+# Defaults that differ from the CLI: the API does not write files or open
+# image windows unless asked to.
+_API_DEFAULT_OVERRIDES: dict[str, Any] = {
+    "no_plot": True,
+    "output_csv": None,
+}
+
+
+def _raise_value_error(message: str) -> None:
+    raise ValueError(message)
+
+
+def _build_api_parser():
+    parser = _build_cli_parser()
+    parser.error = _raise_value_error
+    return parser
+
+
+def cli_defaults() -> dict[str, Any]:
+    """Return every accepted keyword argument with its default value."""
+    defaults = vars(_build_cli_parser().parse_args([]))
+    defaults.update(_API_DEFAULT_OVERRIDES)
+    return defaults
+
+
+def _normalize_option(key: str, value: Any) -> Any:
+    if isinstance(value, PathLike):
+        return str(value)
+    if key == "add_tautomers" and isinstance(value, str):
+        return [value]
+    if key == "add_tautomers" and value is not None:
+        return [str(v) for v in value]
+    return value
+
+
+def run(smiles: str, **options: Any) -> PeaceResult:
+    """
+    Run PEACE on ``smiles`` with the same options as the CLI.
+
+    Raises ``TypeError`` for unknown options and ``ValueError`` for invalid
+    option combinations (the cases where the CLI would exit with an error).
+    """
+    parser = _build_api_parser()
+    args = parser.parse_args([])
+    for key, value in _API_DEFAULT_OVERRIDES.items():
+        setattr(args, key, value)
+
+    valid_keys = set(vars(args))
+    unknown = sorted(set(options) - valid_keys)
+    if unknown:
+        raise TypeError(
+            f"Unknown PEACE option(s): {', '.join(unknown)}. "
+            "See peace.cli_defaults() for accepted keyword arguments."
+        )
+
+    args.smiles = str(smiles)
+    for key, value in options.items():
+        setattr(args, key, _normalize_option(key, value))
+
+    return run_from_args(parser, args, print_results=False)
+
+
+def enumerate_protomers(
+    smiles: str,
+    *,
+    charge_min: int = 0,
+    charge_max: int = 0,
+    **options: Any,
+) -> PeaceResult:
+    """Enumerate tautomers and protomers over ``[charge_min, charge_max]`` without QM calculations."""
+    if options.get("solvation"):
+        raise ValueError("enumerate_protomers() does not run solvation; use solvate() instead.")
+    options.pop("solvation", None)
+    return run(smiles, charge_min=charge_min, charge_max=charge_max, solvation=False, **options)
+
+
+def solvate(
+    smiles: str,
+    *,
+    charge_min: int = 0,
+    charge_max: int = 0,
+    **options: Any,
+) -> PeaceResult:
+    """Enumerate tautomers/protomers and compute solution-phase free energies and populations."""
+    options.pop("solvation", None)
+    return run(smiles, charge_min=charge_min, charge_max=charge_max, solvation=True, **options)

peace_protomer-0.1.0/peace/calculators/__init__.py

@@ -0,0 +1,69 @@
+from .aimnet2 import run_aimnet2_optimization, run_aimnet2_single_point_energy
+from .common import DEFAULT_TEMPERATURE_K, EV_TO_KCAL_MOL, HARTREE_TO_KCAL_MOL, float_regex, parse_last_float
+from .orca import (
+    orca_opt_keyword,
+    orca_solvent_keyword,
+    run_orca_frequencies,
+    run_orca_optimization,
+    run_orca_single_point_energy,
+    run_orca_solvation_single_point,
+    spin_multiplicity,
+    verify_orca_executable,
+)
+from .settings import CalculatorSettings, OrcaSettings
+from .xtb import (
+    XtbFatalError,
+    parse_xtb_rrho_contrib_hartree,
+    parse_xtb_solvent_free_energy_hartree,
+    parse_xtb_total_energy_hartree,
+    report_xtb_fatal_and_exit,
+    run_cpcmx_single_point,
+    run_gxtb_hessian_and_parse_energies,
+    run_gxtb_optimization,
+    run_gxtb_single_point_energy,
+    run_hessian_and_parse_energies,
+    run_xtb_command,
+    run_xtb_optimization,
+    run_xtb_single_point_energy,
+)
+from .xtb2 import (
+    run_gxtb_hessian_and_parse_energies as run_gxtb2_hessian_and_parse_energies,
+    run_gxtb_optimization as run_gxtb2_optimization,
+    run_gxtb_single_point_energy as run_gxtb2_single_point_energy,
+)
+
+__all__ = [
+    "DEFAULT_TEMPERATURE_K",
+    "HARTREE_TO_KCAL_MOL",
+    "EV_TO_KCAL_MOL",
+    "CalculatorSettings",
+    "OrcaSettings",
+    "XtbFatalError",
+    "float_regex",
+    "orca_opt_keyword",
+    "orca_solvent_keyword",
+    "parse_last_float",
+    "parse_xtb_rrho_contrib_hartree",
+    "parse_xtb_solvent_free_energy_hartree",
+    "parse_xtb_total_energy_hartree",
+    "report_xtb_fatal_and_exit",
+    "run_aimnet2_optimization",
+    "run_aimnet2_single_point_energy",
+    "run_cpcmx_single_point",
+    "run_gxtb_hessian_and_parse_energies",
+    "run_gxtb2_hessian_and_parse_energies",
+    "run_gxtb_optimization",
+    "run_gxtb2_optimization",
+    "run_gxtb_single_point_energy",
+    "run_gxtb2_single_point_energy",
+    "run_hessian_and_parse_energies",
+    "run_orca_frequencies",
+    "run_orca_optimization",
+    "run_orca_single_point_energy",
+    "run_orca_solvation_single_point",
+    "run_xtb_command",
+    "run_xtb_optimization",
+    "run_xtb_single_point_energy",
+    "spin_multiplicity",
+    "verify_orca_executable",
+]

peace_protomer-0.1.0/peace/calculators/aimnet2.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import traceback
+from pathlib import Path
+from typing import Callable, Optional
+
+from .common import EV_TO_KCAL_MOL
+
+
+def run_aimnet2_single_point_energy(
+    *,
+    scratch_dir: Path,
+    xyz_path: Path,
+    charge: int,
+    dry_run: bool,
+    log_paths: list[Path],
+    log_status: Callable[[list[Path], str, str], None],
+    model: str = "aimnet2",
+) -> tuple[Optional[float], Optional[float]]:
+    if dry_run:
+        log_status(log_paths, "SKIP", "dry_run; skipping AIMNet2 SP")
+        return None, None
+    try:
+        from ase.io import read
+        from aimnet.calculators import AIMNet2ASE
+    except Exception as exc:
+        raise RuntimeError(
+            "AIMNet2 dependencies are unavailable. Install 'aimnet[ase]' for AIMNet2 support."
+        ) from exc
+
+    log_status(log_paths, "STEP", f"running AIMNet2 SP on {xyz_path.name} model={model} charge={charge}")
+    try:
+        atoms = read(str(xyz_path))
+        atoms.calc = AIMNet2ASE(model, charge=int(charge))
+        energy_ev = float(atoms.get_potential_energy())
+        energy_kcal_mol = energy_ev * EV_TO_KCAL_MOL
+    except Exception as exc:
+        err = "".join(traceback.format_exception_only(type(exc), exc)).strip()
+        log_status(log_paths, "FAIL", f"AIMNet2 SP failed: {err}")
+        raise RuntimeError(f"AIMNet2 SP calculation failed: {err}") from exc
+
+    log_path = scratch_dir / "aimnet2sp_run.log"
+    log_path.write_text(
+        f"xyz_path={xyz_path}\nmodel={model}\ncharge={charge}\nenergy_ev={energy_ev}\nenergy_kcal_mol={energy_kcal_mol}\n",
+        encoding="utf-8",
+    )
+    log_status(log_paths, "OK", f"saved AIMNet2 SP summary to {log_path.name}")
+    return energy_kcal_mol, energy_ev
+
+
+def run_aimnet2_optimization(
+    *,
+    scratch_dir: Path,
+    input_xyz_path: Path,
+    charge: int,
+    dry_run: bool,
+    log_paths: list[Path],
+    log_status: Callable[[list[Path], str, str], None],
+    model: str = "aimnet2",
+    fmax: float = 0.01,
+    max_steps: int = 200,
+) -> tuple[Path, Optional[float], Optional[float]]:
+    optimized_xyz_path = scratch_dir / "aimnet2opt.xyz"
+    if dry_run:
+        log_status(log_paths, "SKIP", "dry_run; skipping AIMNet2 optimization")
+        return optimized_xyz_path, None, None
+    try:
+        from ase.io import read, write
+        from ase.optimize import LBFGS
+        from aimnet.calculators import AIMNet2ASE
+    except Exception as exc:
+        raise RuntimeError(
+            "AIMNet2 dependencies are unavailable. Install 'aimnet[ase]' for AIMNet2 support."
+        ) from exc
+
+    log_status(
+        log_paths,
+        "STEP",
+        f"running AIMNet2 optimization on {input_xyz_path.name} model={model} charge={charge} fmax={fmax}",
+    )
+    try:
+        atoms = read(str(input_xyz_path))
+        atoms.calc = AIMNet2ASE(model, charge=int(charge))
+        opt = LBFGS(atoms, logfile=str(scratch_dir / "aimnet2opt_run.log"))
+        opt.run(fmax=float(fmax), steps=int(max_steps))
+        write(str(optimized_xyz_path), atoms)
+        energy_ev = float(atoms.get_potential_energy())
+        energy_kcal_mol = energy_ev * EV_TO_KCAL_MOL
+    except Exception as exc:
+        err = "".join(traceback.format_exception_only(type(exc), exc)).strip()
+        log_status(log_paths, "FAIL", f"AIMNet2 optimization failed: {err}")
+        raise RuntimeError(f"AIMNet2 optimization failed: {err}") from exc
+
+    log_status(log_paths, "OK", f"AIMNet2 optimization produced {optimized_xyz_path.name}")
+    return optimized_xyz_path, energy_kcal_mol, energy_ev

peace_protomer-0.1.0/peace/calculators/common.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+HARTREE_TO_KCAL_MOL = 627.5094740631
+EV_TO_KCAL_MOL = 23.06054783061903
+
+# Default thermochemical / Boltzmann temperature (Kelvin).
+DEFAULT_TEMPERATURE_K = 298.15
+
+# xTB --opt convergence presets, loosest to tightest.
+OPT_CONVERGENCE_LEVELS: tuple[str, ...] = (
+    "crude",
+    "sloppy",
+    "loose",
+    "lax",
+    "normal",
+    "tight",
+    "vtight",
+    "extreme",
+)
+
+
+def looser_opt_convergence_level(opt_level: str) -> Optional[str]:
+    """Return the next-looser convergence preset, or None if already at crude."""
+    try:
+        idx = OPT_CONVERGENCE_LEVELS.index(opt_level)
+    except ValueError:
+        return None
+    if idx == 0:
+        return None
+    return OPT_CONVERGENCE_LEVELS[idx - 1]
+
+
+def opt_convergence_retry_levels(opt_level: str) -> list[str]:
+    """Return convergence presets to try, from opt_level down to crude."""
+    try:
+        idx = OPT_CONVERGENCE_LEVELS.index(opt_level)
+    except ValueError:
+        return [opt_level]
+    return list(OPT_CONVERGENCE_LEVELS[idx::-1])
+
+
+def float_regex() -> str:
+    return r"[-+]?(?:\d+\.\d*|\.\d+|\d+)(?:[eE][-+]?\d+)?"
+
+
+def parse_last_float(patterns: list[str], text: str) -> Optional[float]:
+    for pat in patterns:
+        matches = list(re.finditer(pat, text, flags=re.IGNORECASE | re.MULTILINE))
+        if not matches:
+            continue
+        for m in reversed(matches):
+            try:
+                return float(m.group(1))
+            except ValueError:
+                continue
+    return None