Merge pull request #142 from marcelmbn/dev/gp3_ipea

Update `xtb` constraints

Author: marcelmbn

CHANGELOG.md

@@ -1,24 +1,33 @@
 # Changelog
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- Distance constraints for xTB (normalized parsing, config validation, runtime enforcement, and optional integration test).
+
 ## [0.6.0] - 2025-04-01
+
 ### Changed
+
 - to set the elemental composition it is now possible to use dicts with not only int but also the element symbols (str)
 - dict keys for elemental compositions will now always be checked for validity
 - Renamed GP3-xTB to g-xTB
 - Moved constants and (empirical) parameters to the `data` module
 - Default for optimization cycles in the postprocessing step set to program default (convergence)
 
 ### Deprecated
+
 - Nothing will be printed while multiple molecules are generated in parallel, tqdm-based progress bar instead
 - Some debugging statements from generate had to be removed (esp. w.r.t. early stopping)
 
 ### Added
+
 - `GXTBConfig` class for the g-xTB method, supporting SCF cycles check
 - support for TURBOMOLE as QM engine
 - updated the parallelization to work over the number of molecules
@@ -27,14 +36,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - support for a manually defined temporary directory for the QM calculations
 
 ### Fixed
+
 - version string is now correctly formatted and printed
 - precision (# significant digits) of the coordinate files (`get_coord_str` and `get_xyz_str`) increased from 7 to 14
 - catch encoding errors when reading `Turbomole._run_opt` output files
 - bug in the parallelization, leading to a dead `mindlessgen` execution as a consequence of not allowing the required number of cores
 - stop_event checked before every external call to avoid unnecessary executions
 
 ## [0.5.0] - 2024-12-16
+
 ### Changed
+
 - vdW radii scaling parameter can now be adjusted via `mindlessgen.toml` or CLI
 - check_distance function now checks based on the sum of the van der Waals radii and a scaling factor acessible via `mindlessgen.toml` or CLI
 - better type hints for `Callables`
@@ -46,6 +58,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - modify atom list adaption to `element_composition` such that a random integer in the given range is taken and not the lower/upper bound
 
 ### Fixed
+
 - unit conversion for (currenly unused) vdW radii from the original Fortran project
 - minor print output issues (no new line breaks, more consistent verbosity differentiation, ...)
 - bug in `postprocess_mol` which led to an unassigned return variable in the single-point case
@@ -55,6 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - legacy pseudo random number generation removed and replaced by `np.random.default_rng()` for avoiding interference with other packages
 
 ### Added
+
 - support for the novel "g-xTB" method (previous working title: GP3-xTB)
 - function which contracts the coordinates after the initial generation
 - function which is able to printout the xyz coordinates to the terminal similar to the `.xyz` layout
@@ -64,13 +78,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `element_composition` and `forbidden_elements` can now be directly set to a `dict` or `list`, respectively, via API access
 
 ### Breaking Changes
+
 - Removal of the `dist_threshold` flag and in the `-toml` file.
 - The number of unpaired electrons (`Molecule.uhf`) is now set to 0 if `xtb` is used as `QMMethod` and a lanthanide is within the molecule to match the `f-in-core` approximation.
 - "Contract Coordinates" functionality set to `true` by default in the `mindlessgen.toml` file.
 - `basename.UHF` and `basename.CHRG` are only written to disk if they differ from the default value (0 and 0, respectively).
 
 ## [0.4.0] - 2024-09-19
+
 ### Changed
+
 - Default file name of `.xyz` file contains prefix `mlm_`
 - Comment line of `.xyz` file contains the total charge and number of unpaired electrons
 - Default ORCA calculation changed from r2SCAN-3c to PBE/def2-SVP
@@ -82,12 +99,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `mindless.molecules` file is written continuously during generation
 
 ### Fixed
+
 - `test_iterative_optimization` more deterministic
 - wrong atom range check in for the isomerization mode ([#21](https://github.com/grimme-lab/MindlessGen/pull/21))
 - `forbidden_elements` and `element_composition` influences hydrogen and organic element addition
 - more realistic default `mindlessgen.toml` entries
 
 ### Added
+
 - Optimization via DFT in the post-processing step
 - Detailed input of ORCA settings (functional, basis, grid size, SCF cycles, ...) possible
 - `min_num_atoms` and `max_num_atoms` consistency check
@@ -101,20 +120,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `PyPi` and `TestPyPi` upload of releases (new workflow)
 
 ## [0.3.0] - 2024-08-20
+
 ### Breaking Changes
+
 - ...
 
 ### Added
+
 - ...
 
 ### Changed
+
 - ...
 
 ### Removed
+
 - ...
 
 ### Fixed
+
 - ...
 
 ### Deprecations
+
 - ...

README.md

@@ -167,22 +167,26 @@ When using the program for academic purposes, please cite _1)_ the new Python im
 
 
 1.  The new implementation of `mindlessgen`, accompanied by a benchmark study evaluating density functionals, semiempirical quantum-mechanical methods, and machine learning potentials:
-    T. Gasevic, M. Müller, J. Schöps, S. Lanius, J. Hermann, S. Grimme, and A. Hansen, “Chemical Space Exploration with Artificial ”Mindless” Molecules,” (2025)
+    T. Gasevic, M. Müller, J. Schöps, S. Lanius, J. Hermann, S. Grimme, and A. Hansen, “Chemical Space Exploration with Artificial ‘Mindless’ Molecules,” _J. Chem. Inf. Model._ **65**(18), 9576–9587 (2025).
+
     ```
-    @misc{gasevicChemicalSpaceExploration2025,
-      title = {Chemical {{Space Exploration}} with {{Artificial}} ''{{Mindless}}'' {{Molecules}}},
+    @article{gasevicChemicalSpaceExploration2025,
+      title = {Chemical Space Exploration with Artificial "Mindless" Molecules},
       author = {Gasevic, Thomas and M{\"u}ller, Marcel and Sch{\"o}ps, Jonathan and Lanius, Stephanie and Hermann, Jan and Grimme, Stefan and Hansen, Andreas},
-      year = {2025},
-      month = jun,
-      publisher = {ChemRxiv},
-      doi = {10.26434/chemrxiv-2025-rdsd0},
-      urldate = {2025-06-14},
-      archiveprefix = {ChemRxiv},
-      langid = {english},
-      keywords = {benchmarking,DFT,FF,MLIP,SQM}
+      year = 2025,
+      month = sep,
+      journal = {Journal of Chemical Information and Modeling},
+      volume = {65},
+      number = {18},
+      pages = {9576--9587},
+      publisher = {American Chemical Society},
+      issn = {1549-9596},
+      doi = {10.1021/acs.jcim.5c01364},
+      urldate = {2025-10-14},
     }
+    ```
 
-2.  The original idea of "mindless" molecules for benchmarking density functional theory:
+3.  The original idea of "mindless" molecules for benchmarking density functional theory:
     M. Korth, and S. Grimme, “Mindless DFT benchmarking,” _J. Chem. Theory Comput._ **5**(4), 993–1003 (2009).
     ```
     @article{korth_mindless_2009,
@@ -202,7 +206,7 @@ When using the program for academic purposes, please cite _1)_ the new Python im
     }
     ```
 
-3.  First use of the novel `mindlessgen` implementation:
+4.  First use of the novel `mindlessgen` implementation:
     M. Müller, T. Froitzheim, A. Hansen, and S. Grimme, “Advanced Charge Extended Hückel (CEH) Model and a Consistent Adaptive Minimal Basis Set for the Elements Z = 1–103,” _J. Phys. Chem. A_ **128**(49), 10723–10736 (2024).
 
     ```

mindlessgen.toml

@@ -87,6 +87,13 @@ ncores = 4
 xtb_path = "/path/to/xtb"
 # > The GFN<n>-xTB method that should be used: Options: <int = 0> -> GFN-0-xTB, <int = 1> -> GFN-1-xTB, <int = 2> -> GFN-2-xTB
 level = 2
+# > Optional shared force constant applied to all distance constraints. Options: <float>
+# distance_constraint_force_constant = 0.5
+# > Define atom-type distance constraints applied during refinement.
+# > Provide element pairs via `pair` and a target distance in Å.
+# [[xtb.distance_constraints]]
+# pair = ["O", "H"]
+# distance = 1.02
 
 [orca]
 # > Path to the orca executable. The names `orca` and `orca_dev` are automatically searched for. Options: <str | Path>

src/mindlessgen/cli/cli_parser.py

@@ -7,6 +7,17 @@
 import argparse
 from collections.abc import Sequence
 from ..__version__ import __version__
+from ..prog import DistanceConstraint
+
+
+def _parse_distance_constraint_arg(value: str) -> DistanceConstraint:
+    """
+    Parse CLI distance constraint specifications formatted as A,B,d.
+    """
+    try:
+        return DistanceConstraint.from_cli_string(value)
+    except (ValueError, TypeError) as exc:
+        raise argparse.ArgumentTypeError(str(exc)) from exc
 
 
 def cli_parser(argv: Sequence[str] | None = None) -> dict:
@@ -251,6 +262,26 @@ def cli_parser(argv: Sequence[str] | None = None) -> dict:
         required=False,
         help="Level of theory to use in xTB.",
     )
+    parser.add_argument(
+        "--xtb-distance-constraint",
+        action="append",
+        type=_parse_distance_constraint_arg,
+        required=False,
+        help=(
+            "Distance constraint applied during xTB optimization. "
+            "Format: ElementA,ElementB,distance (Å). "
+            "Option can be provided multiple times."
+        ),
+    )
+    parser.add_argument(
+        "--xtb-distance-constraint-force-constant",
+        type=float,
+        required=False,
+        help=(
+            "Force constant applied to all xTB distance constraints. "
+            "Provide a positive float value."
+        ),
+    )
 
     ### ORCA specific arguments ###
     parser.add_argument(
@@ -356,6 +387,10 @@ def cli_parser(argv: Sequence[str] | None = None) -> dict:
     rev_args_dict["xtb"] = {
         "xtb_path": args_dict["xtb_path"],
         "level": args_dict["xtb_level"],
+        "distance_constraints": args_dict["xtb_distance_constraint"],
+        "distance_constraint_force_constant": args_dict[
+            "xtb_distance_constraint_force_constant"
+        ],
     }
     # ORCA specific arguments
     rev_args_dict["orca"] = {

src/mindlessgen/prog/__init__.py

@@ -14,6 +14,7 @@
     RefineConfig,
     PostProcessConfig,
     SymmetrizationConfig,
+    DistanceConstraint,
 )
 from .parallel import setup_managers, ResourceMonitor, setup_blocks
 
@@ -31,4 +32,5 @@
     "ResourceMonitor",
     "setup_blocks",
     "SymmetrizationConfig",
+    "DistanceConstraint",
 ]