v0.2.8

Added

• --refine-path default changed to True: The all command now uses recursive path-search by default.
• --thresh-post: Post-processing convergence threshold for the all command.
• --dft-engine [gpu|cpu]: New option in all command to override DFT engine.
• [freq] output line: Frequency analysis now prints all vibrational frequencies in a summary line.
• track_mode_by_overlap: New rsirfo config option (default False) for TS mode tracking strategy.
• TR projection in TS optimization: Translation/rotation projection applied to Cartesian Hessian before eigendecomposition in RS-I-RFO.
• H_double default changed to True: Hessian computation now uses float64 throughout (analytical and FD), improving numerical precision for PHVA.
• Energy plateau convergence fallback: When the energy range over a window of steps falls below a threshold, the optimization is declared converged. Config options: energy_plateau (default true), energy_plateau_thresh (default 1e-4 au ≈ 0.06 kcal/mol), energy_plateau_window (default 50 steps).

Fixed

• trust_max reduced from 0.20 to 0.10 bohr: Prevents energy oscillations near saddle points in large systems.
• EulerPC corrector infinite loop: Bounded loop with gradient norm check to prevent infinite iteration and NaN propagation.
• PDB MODEL/ENDMDL: Single-frame PDB files no longer include MODEL/ENDMDL records.
• PDB MODEL duplication: Reference PDB template now filtered for MODEL/ENDMDL/END.
• PDB trailing newline: Ensured newline before ENDMDL.
• PDB END filter: Correctly handles END with trailing spaces.
• RS-I-RFO image potential: Uses TR-projected Hessian (cur_H_diag) for eigenvector consistency.
• _active_dof_indices: Fixed attribute name in _tr_project_hessian.
• TS mode tracking log: Fixed .argmax() on scalar; replaced print() with self.log().
• Smoke test flags: --exclude-backbone False → --no-exclude-backbone.

v0.2.7

Changes

• DFT --engine CLI option: New --engine gpu|cpu option (default gpu). GPU failure now raises an error instead of silently falling back to CPU.
• DFT auto-ECP: dft subcommand automatically sets mol.ecp for def2-family basis sets.
• xTB error message: Improved error when xtb binary is not found, with installation instructions.
• xTB install docs: Added xTB installation section to getting-started.md (en/ja).
• Smoke test coverage: Added tests for bond-summary, fix-altloc, oniom-import, --refine-path (38 tests total).
• CI: Added bond-summary and pysis to --help smoke loop.
• bond-summary and pysis added to README subcommand table.

Bug Fixes

• Fix global pre-alignment: multi-structure inputs are now globally aligned to the first structure's coordinate frame before pairwise MEP segmentation, ensuring freeze-atom coordinate continuity across segments.
• Fix bond-summary PDB loading: geom_from_pdb_str → geom_from_pdb.
• Fix extract() AMINO_ACIDS global mutation: now exception-safe with try/finally.
• Fix convert_xyz_to_pdb stale file corruption when first frame is skipped.
• Fix DMF mode --out-json convergence status (was always None).

Documentation

• Fix bond.device default in YAML reference and scan docs (cuda → auto).
• Fix calc.return_partial_hessian default in YAML reference (false → true).
• Fix hessian_ff build note: "auto-built during pip install" → "JIT compiled on first use".
• Fix xTB error symptom in troubleshooting (FileNotFoundError → XTBEmbedError).
• Fix dft.md: add --engine to CLI table, remove auto-fallback text.
• Fix path-search.md: -q no longer marked as "Required" (conditional).
• Fix scan.md: add -o short form for --out-dir.
• Fix ja/all.md: correct --scan-lists repetition claim.
• Document Blackwell GPU (RTX 50xx) OOM limitation in dft.md.
• Add bond-summary to index.md subcommand table.

v0.2.6

Changes

• --modified-residue: Register non-standard amino acid residue names for correct backbone truncation and charge assignment in extract and all commands.
• --refine-path default changed to False: The all command now uses single-pass path-opt (GSM) by default. Add --refine-path to enable recursive path-search.
• --out-json: All MLIP subcommands now support --out-json for machine-readable result.json output. summary.yaml migrated to summary.json.
• --freeze-atoms: Available on all subcommands; atom indices unified to 1-based throughout.
• bond-summary subcommand: Detect bond changes between two structures.

Bug Fixes

• Fix PDB element handling: replaced ASE-based PDB write with text-based coordinate replacement to prevent element name corruption (e.g., ZN→N, CA→Ca).
• Fix hess_mm_atoms 1-based conversion: moved YAML-to-internal index conversion to the correct point (YAML read time, not MLMMCore.__init__).
• Fix _resolve_device("auto") falling back to CPU instead of resolving to CUDA.
• Fix zero-mass guard in tsopt.
• Fix scan end_optimizer guard.
• Fix kink HEI endpoint exclusion.
• Fix _to_json numpy/torch handling.
• Fix bare assert in bond_changes.py.
• Fix dft.py dead code check.
• Fix freq.py missing sum_EE_and_thermal_enthalpy_ha field.

v0.2.5

Changes

• ml_hessian_mode unified into hessian_calc_mode
• RFO trust_radius 0.30→0.10, trust_max 0.30→0.20
• IRC: --hess-device, --read-hess; freq: --dump-hess (Hessian reuse)
• tsopt/all: --skip-final-freq
• Auto-shorten absolute paths and suppress consecutive blank lines in CLI output

Fixes

• IRC bisection: fix in-place mutation corrupting displacement arrays
• IRC initial displacement clamp 0.5→3.0 au
• all: --preopt default corrected to True
• extract: --exclude-backbone default changed to False
• path_search: fix missing MLMM_CALC_KW import
• dft.py: fix tmp.cleanup() → tmpdir.cleanup()

Docs

• fix defaults, YAML keys, and tables across EN/JA docs
• Fix dark mode toggle (3-state → 2-state)

v0.2.4

See CHANGELOG.md

v0.2.3

What's Changed

Added

• GitHub Pages deployment and PyPI release workflows.
• Bidirectional scan (4-tuple) documentation (EN/JA).

Fixed

• Regenerated CLI reference docs to match current --help output.
• Documentation accuracy: defaults, YAML examples, EN/JA alignment.
• Generalized UMA-specific wording to MLIP where applicable.
• Improved hessian_ff JIT build error message.
• Fixed release.yml to checkout exact tag with fetch-tags for correct setuptools-scm version.

Full Changelog: https://github.com/t-0hmura/mlmm_toolkit/blob/main/CHANGELOG.md

v0.2.2

What's Changed

Added

• GitHub Pages deployment and PyPI release workflows.
• Bidirectional scan (4-tuple) documentation (EN/JA).

Fixed

• Regenerated CLI reference docs to match current --help output.
• Documentation accuracy: defaults, YAML examples, EN/JA alignment.
• Generalized UMA-specific wording to MLIP where applicable.
• Improved hessian_ff JIT build error message.
• Fixed release.yml to checkout exact tag ref for correct setuptools-scm version.

Full Changelog: https://github.com/t-0hmura/mlmm_toolkit/blob/main/CHANGELOG.md

v0.2.1

What's Changed

Added

• GitHub Pages deployment and PyPI release workflows.
• Bidirectional scan (4-tuple) documentation (EN/JA).

Fixed

• Regenerated CLI reference docs to match current --help output.
• Documentation accuracy: defaults, YAML examples, EN/JA alignment.
• Generalized UMA-specific wording to MLIP where applicable.
• Improved hessian_ff JIT build error message.

Full Changelog: https://github.com/t-0hmura/mlmm_toolkit/blob/main/CHANGELOG.md

v0.2.0

Complete rewrite from mlmm (v0.1.1) to mlmm-toolkit (v0.2.0).
This release replaces the previous pysisyphus-wrapper architecture with a unified Click-based CLI toolkit. The package name, CLI interface, dependency stack, and internal architecture have all changed.

Breaking Changes

• Package name: mlmm-toolkit on PyPI. Install with pip install mlmm-toolkit.
• CLI completely redesigned: The old entry points (mlmm, def_ml_region, bond_scan, ts_search, energy_summary, trj2fig, add_elem_info, get_freeze_indices, xyz_geom2pdb) are replaced by a single mlmm <subcommand> interface with 21 subcommands.
• OpenMM removed: MM calculations now use hessian_ff, a bundled C++ native extension for Amber force fields. OpenMM and OpenMM-CUDA-12 are no longer dependencies.
• RDKit removed: No longer required.
• pysisyphus bundled: No longer installed from a separate git repository; a modified fork is included in the package.
• fairchem-core from PyPI: No longer installed from a custom git fork.
• numpy constraint relaxed: numpy<2.0 → numpy>=1.24 (NumPy 2.x compatible).
• Configuration: Inline kwargs replaced by a centralized defaults.py as the single source of truth for all default values.

Added — CLI & Workflow

• mlmm all: End-to-end workflow command. Given PDB files (R → P), automatically extracts active-site pockets, generates MM parameters, assigns ONIOM layers, runs MEP search, and optionally performs TS optimization, IRC, vibrational analysis, and single-point DFT — all in one invocation.
• mlmm opt: Single-structure geometry optimization with LBFGS (grad mode) or RFO (hess mode) with microiteration support.
• mlmm scan / scan2d / scan3d: 1D, 2D, and 3D constrained distance scans along user-specified atom pairs.
• mlmm path-search: Recursive minimum-energy path search with GSM (Growing String Method) and DMF (Direct Max Flux).
• mlmm path-opt: Single-pass MEP optimization (GSM or DMF).
• mlmm tsopt: Transition-state optimization (dimer method with partial Hessian, or RS-I-RFO with full Hessian).
• mlmm irc: Intrinsic reaction coordinate calculation from a TS geometry. Outputs forward_last.pdb and backward_last.pdb endpoint structures.
• mlmm freq: Vibrational analysis and thermochemistry (partial or full Hessian).
• mlmm dft: GPU-accelerated single-point DFT via PySCF / gpu4pyscf (pip install "mlmm-toolkit[dft]").
• mlmm extract: Active-site pocket extraction from full protein-ligand PDB structures.
• mlmm mm-parm: Automatic Amber parm7/rst7 generation via AmberTools (tleap + GAFF2/AM1-BCC).
• mlmm define-layer: Assign 3-layer ML/MM partitioning via B-factor encoding (ML=0, MovableMM=10, FrozenMM=20).
• mlmm oniom-export / oniom-import: Gaussian/ORCA ONIOM input/output interoperability.
• mlmm add-elem-info: Fix missing or incorrect PDB element columns.
• mlmm fix-altloc: Resolve alternate location indicators in PDB files.
• mlmm energy-diagram: Plot energy profiles with Plotly (interactive HTML + static PNG).
• mlmm trj2fig: Trajectory visualization (PNG snapshots from XYZ trajectories).

Added — Core Features

• Multi-backend MLIP support: UMA (default), ORB, MACE, AIMNet2 — selectable via -b/--backend on all subcommands.
• ONIOM-like ML/MM decomposition: E = E_MM_real + E_ML_model − E_MM_model with link-atom Jacobian transformation.
• hessian_ff: Bundled C++ native extension for analytical Amber force field energies, forces, and Hessians (replaces OpenMM).
• Microiteration scheme: Efficient optimization of large ML/MM systems (~10,000 atoms) by separating ML and MM degrees of freedom.
• xTB embed-charge correction: Optional point-charge embedding for the ML region (--embedcharge).
• Partial Hessian approach: Compute Hessians only for the ML region + boundary atoms, enabling TS optimization and frequency analysis on large systems.
• Automatic versioning: setuptools-scm replaces hard-coded __version__.
• Progressive help: --help shows primary options; --help-advanced shows the full option set.
• DefaultGroup: Lazy-loading Click subcommand architecture with automatic boolean normalization (--flag/--no-flag and --flag True/False both supported).

Added — Dependencies & Extras

• Optional backends: pip install "mlmm-toolkit[orb]", "mlmm-toolkit[mace]", "mlmm-toolkit[aimnet2]".
• Optional DFT: pip install "mlmm-toolkit[dft]" for PySCF + gpu4pyscf-cuda12x + CuPy.
• Optional PDBFixer: pip install "mlmm-toolkit[pdbfixer]" for hydrogen addition.
• New core dependencies: click, torch_geometric, torch_scatter, pyparsing, tabulate.
• Bundled packages: pysisyphus (modified fork), thermoanalysis, hessian_ff.

Added — Documentation & Testing

• Bilingual documentation (English + Japanese) under docs/ and docs/ja/.
• Per-subcommand reference docs with CLI tables and YAML configuration examples.
• CONTRIBUTING.md with contributor guidelines.
• GitHub Actions CI: pytest.yml, smoke_test.yml, docs_quality.yml.
• 198 unit tests with pytest --timeout=120.
• Smoke test suite: 34 end-to-end tests covering all subcommands.
• Working examples in examples/toy_system/ and examples/methyltransferase/.

Fixed (relative to v0.1.1)

• IRC energy-based initial displacement: Added step_length clamp (max 0.5 au) to prevent divergence when min_eigval ≈ 0.
• Hessian cache: Fixed set_calculator() clearing within_partial_hessian before cart_hessian assignment.
• HessianOptimizer: Fixed GPU/CPU device mismatch in hessian_recalc.
• Frequency analysis: Added float64 enforcement and explicit (H+Hᵀ)/2 symmetrization.
• PDB element inference: Fixed _infer_element_from_pdb_atom_name() misidentifying protein hydrogens (e.g., HG2 → Hg). Now uses residue-context-aware guess_element().
• Silent except Exception: pass blocks converted to logger.debug(...) across all modules.
• Charge derivation: Uses --model-pdb instead of full input when provided.
• TypeError in _pseudo_irc_and_match when mapping value is None.

Architecture — v0.1.1 → v0.2.0

Aspect	v0.1.1 (mlmm)	v0.2.0 (mlmm-toolkit)
Package name	mlmm	mlmm-toolkit
Codebase size	~3,700 lines (13 files)	~35,000 lines (40+ files)
CLI framework	8 separate entry points (argparse)	1 entry point, 21 Click subcommands
MM backend	OpenMM (finite difference)	hessian_ff (analytical C++)
ML backends	UMA, AIMNet2	UMA, ORB, MACE, AIMNet2
pysisyphus	Git dependency	Bundled (modified fork)
Configuration	Inline kwargs	Centralized defaults.py
Documentation	README only	Full docs
CI/CD	None	GitHub Actions (3 workflows)
Tests	None	198 unit + 34 smoke tests

v0.1.1

To simplify the installation instructions and clarify dependency handling, we have modified the setup so that fairchem-core and aimnet are now installed from forked repositories.

Quick install (including fairchem-core and pysisyphus installation)

For CUDA 12.6:

pip install torch==2.6.0 --index-url https://download.pytorch.org/whl/cu126
pip install git+https://github.com/t-0hmura/mlmm_toolkit.git
huggingface-cli login

For CUDA 12.8 (recommended for RTX 50 series):

pip install torch==2.7.0 --index-url https://download.pytorch.org/whl/cu128
pip install git+https://github.com/t-0hmura/mlmm_toolkit.git
huggingface-cli login