v0.1.8 upload

- The orbital-ML (`orb_ml`) **backend for xTB** is now `tblite` library rather than `xtb` executable.
- **FJK + tblite** now works end-to-end, with a dedicated (but admittedly probably machine-dependent) test (`test_FJK_tblite.py`).

- **Local and global SLATM** functions optimized and now JIT-compatible.
- **Numba caching** for the more important representation functions.
- **Fixed Torch compilation** for some previously broken functions.
- Dedicated **representation calculators** for FCHL19, Coulomb Matrix, and Bag-of-Bonds, with more constructor options.

- **Revised `test_mode`** to generate diagonal sign matrices via "continuous" rather than "discontinuous" sign-flipping, making the tests more reproducible.
- Fixed `l2reg` optimization for SORF models.
- Corrected simple-shift calculation for MSORF.
- Optimized calculation of regression coefficients for simple fit (no hyperparameter optimization).

- Added a fast "short" hyperparameter-optimization mode to the model classes, plus more convenient options for it.
- Grid optimization can now be used instead of BOSS.

- `stderr` is preserved after an `embarrassingly_parallel` failure.
- **Safer defaults**:
  - `suppress_openmp=False` since it causes problems for bulky representations like aSLATM,
  - atom-level representation parallelization off by default but controllable via an environmental variable,
  - process spawning is spawn-based by default but controllable by a submodule-level routine.
- `multiprocessing.Pool` instances can now be reused, additional pool-creation options.

- Model classes can now reuse precomputed representation vectors stored in `Compound` class.

- Conversion coefficients (`au_kcal`, `au_eV`, `Angstrom_Bohr`, `Debye_au`) updated to CODATA 2022 recommended values.

- should no longer crash on **macOS**.
- now requires **Python 3.11** due to some newer syntax being used.

- Revised scripts for [v3 of MSORF manuscript](https://arxiv.org/abs/2505.21247v3).

- Updated reference conda environment (see `tests/reference_environments/qml2_test_2025_11_26.yml`).
- Tests for all models (except MSORF) use grid rather than BOSS optimization for reproducibility.

Author: kvkarandashev

.pre-commit-config.yaml

@@ -9,6 +9,9 @@ repos:
         -   id: end-of-file-fixer
         -   id: trailing-whitespace
         -   id: check-added-large-files
+            # tests/test_data/ holds committed test fixtures (e.g. the ~1.7MB
+            # qm7.tar.gz); the default 500KB cap still guards all source.
+            exclude: ^tests/test_data/
         -   id: check-ast
         -   id: check-json
         -   id: debug-statements

Makefile

@@ -34,6 +34,7 @@ test: test-env
 	$(python) -m pytest -rs ./tests
 
 install:
+	$(python) uninstall_script.py $(pip)
 	$(pip) install .$(OPT)
 
 $(doxygen_main):

README.md

@@ -4,20 +4,30 @@ Code repo for convenient usage of methods developed in the [`chemspacelab`](http
 
 ## :wrench: Installation
 
+**WARNING:** As of 2025.09, due to conflict of several of the code dependencies we recommend only using it on Python 3.12.
+
 Install with:
 
    ```bash
    pip install .
    ```
-or, if `makefile` is installed,
+If a qml2 installation is already present, we recommend uninstalling it first via
+
+```bash
+pip uninstall qml2
+```
+to make sure the cache of Numba-compiled functions is cleared. The two actions can be done together in a single command if `makefile` is installed with
 
    ```bash
    make install
    ```
+
 Some parts of the code depend on additional dependencies that can be installed with the corresponding optional dependecies flag. The three defined for this package are
 
 - `orb_ml` - for FJK (machine learning from orbital information).
 
+- `xtb` - use [`tblite`](https://github.com/tblite/tblite) to combine orbital representations with xTB calculations.
+
 - `models` - for hyperparameter optimization procedures in `qml2.models` and `qml2.multilevel_sorf`.
 
 - `morfeus` - for applications dependend on `morfeus-ml` package (everything related to conformer ensemble generation).
@@ -66,14 +76,15 @@ This will create `manual.html` file that can be opened with an Internet browser.
 
 `NUMBA_NUM_THREADS` - since the code is written in Numba OpenMP parallelization is mostly controlled via this variable.
 
-`QML2_NUM_PROCS` - number of processes spawned by parts of the code parallelized via `python.multiprocessing` (training set representations in model-related classes, `pyscf` calculations made by `OML_Compound_list` attribute calls). For limiting number of OpenMP threads spawned in turn by these processes use suppress options (such as `KRRModel` class's `training_reps_suppress_openmp` option). Also see `parallelization.set_default_num_procs`.
+`QML2_DEBUG` - set as `1` to compile Numba routines inside QML2 with debug info.
 
 `QML2_NUM_PROCS` - number of processes spawned by parts of the code parallelized via `python.multiprocessing` (training set representations in model-related classes, `pyscf` calculations made by `OML_Compound_list` attribute calls). For limiting number of OpenMP threads spawned in turn by these processes use suppress options (such as `KRRModel` class's `training_reps_suppress_openmp` option). Also see `parallelization.set_default_num_procs`.
 
 `QML2_AVOID_NUMBA_NUMPY_PARALLELIZATION` - some Numba routines in the code call in parallel Numpy routines, which creates problems in some setups (e.g. when both Numba and Numpy try to parallelize over a large number of threads without taking each other into account). Setting this environmental variable to `1` disables Numba parallelization in such routines, leaving them to be parallelized exclusively with Numpy.
 
 `QML2_AVOID_SORF_NUMBA_PARALLELIZATION` - setting this environmental variable to `1` disables Numba parallelization over feature vectors for SORF routines in `qml2.kernels.sorf` and `qml2.kernels.gradient_sorf` (also referred to in the corresponding `qml2.models` classes). Helps if reductors are used in systems where Numba and Numpy try to parallelize simultaneously (see `QML2_AVOID_NUMBA_NUMPY_PARALLELIZATION`).
 
+`QML2_NUMBA_REP_PARALLELIZATION` - setting this environmental variable to `1` enables Numba parallelization of representation functions (e.g. w.r.t. atoms). Default is `0`.
 
 ### Experimental
 

examples/models/ex_Coulomb_Matrix_SORF_model.py

@@ -7,45 +7,52 @@
 from qml2 import Compound
 from qml2.models.loss_functions import MAE
 from qml2.models.sorf import SORFModel
+from qml2.representations.calculators import CMCalculator
 
-xyzs = []
-energies = []
 
-training_set_size = 2001
-test_set_size = 1000
-num_mols = training_set_size + test_set_size
+def main():
+    xyzs = []
+    energies = []
 
-with open("../../tests/test_data/hof_qm7.txt") as csvfile:
-    reader = csv.reader(csvfile, delimiter=" ")
-    all_rows = list(reader)
-    random.shuffle(all_rows)
-    for row in all_rows[:num_mols]:
-        xyzs.append(row[0])
-        energies.append(float(row[1]))
+    training_set_size = 2001
+    test_set_size = 1000
+    num_mols = training_set_size + test_set_size
 
-energies = np.array(energies)
+    with open("../../tests/test_data/hof_qm7.txt") as csvfile:
+        reader = csv.reader(csvfile, delimiter=" ")
+        all_rows = list(reader)
+        random.shuffle(all_rows)
+        for row in all_rows[:num_mols]:
+            xyzs.append(row[0])
+            energies.append(float(row[1]))
 
-compounds = []
-with tarfile.open("../../tests/test_data/qm7.tar.gz") as tar:
-    for xyz_name in xyzs:
-        xyz = tar.extractfile(xyz_name)
-        comp = Compound(xyz=xyz)
-        compounds.append(comp)
+    energies = np.array(energies)
 
-train_compounds = compounds[:training_set_size]
-test_compounds = compounds[training_set_size:]
+    compounds = []
+    with tarfile.open("../../tests/test_data/qm7.tar.gz") as tar:
+        for xyz_name in xyzs:
+            xyz = tar.extractfile(xyz_name)
+            comp = Compound(xyz=xyz)
+            compounds.append(comp)
 
-train_quantities = energies[:training_set_size]
-test_quantities = energies[training_set_size:]
+    train_compounds = compounds[:training_set_size]
+    test_compounds = compounds[training_set_size:]
 
-# NOTE: we can use shift_quantities=True, shifting the labels by their mean, but since in this example they are extensive that is not likely to make the results better.
-model = SORFModel(shift_quantities=True)
+    train_quantities = energies[:training_set_size]
+    test_quantities = energies[training_set_size:]
 
-model.train(training_compounds=train_compounds, training_quantities=train_quantities)
+    # NOTE: we can use shift_quantities=True, shifting the labels by their mean, but since in this example they are extensive that is not likely to make the results better.
+    model = SORFModel(shift_quantities=True, representation_function=CMCalculator(size=29))
 
-print("Optimized sigma:", model.sigma)
-print("Optimized l2reg divided by average kernel element:", model.l2reg_diag_ratio)
+    model.train(training_compounds=train_compounds, training_quantities=train_quantities)
 
-predictions = model.predict_from_compounds(test_compounds)
-print("Prediction MAE:", MAE()(predictions - test_quantities))
-print("Test set quantity STD:", np.std(test_quantities))
+    print("Optimized sigma:", model.sigma)
+    print("Optimized l2reg divided by average kernel element:", model.l2reg_diag_ratio)
+
+    predictions = model.predict_from_compounds(test_compounds)
+    print("Prediction MAE:", MAE()(predictions - test_quantities))
+    print("Test set quantity STD:", np.std(test_quantities))
+
+
+if __name__ == "__main__":
+    main()

examples/models/ex_Coulomb_Matrix_model.py

@@ -7,45 +7,53 @@
 from qml2 import Compound
 from qml2.models.krr import KRRModel
 from qml2.models.loss_functions import MAE
+from qml2.representations.calculators import CMCalculator
 
-xyzs = []
-energies = []
 
-training_set_size = 2001
-test_set_size = 1000
-num_mols = training_set_size + test_set_size
+def main():
+    xyzs = []
+    energies = []
 
-with open("../../tests/test_data/hof_qm7.txt") as csvfile:
-    reader = csv.reader(csvfile, delimiter=" ")
-    all_rows = list(reader)
-    random.shuffle(all_rows)
-    for row in all_rows[:num_mols]:
-        xyzs.append(row[0])
-        energies.append(float(row[1]))
+    training_set_size = 2001
+    test_set_size = 1000
+    num_mols = training_set_size + test_set_size
 
-energies = np.array(energies)
+    with open("../../tests/test_data/hof_qm7.txt") as csvfile:
+        reader = csv.reader(csvfile, delimiter=" ")
+        all_rows = list(reader)
+        random.shuffle(all_rows)
+        for row in all_rows[:num_mols]:
+            xyzs.append(row[0])
+            energies.append(float(row[1]))
 
-compounds = []
-with tarfile.open("../../tests/test_data/qm7.tar.gz") as tar:
-    for xyz_name in xyzs:
-        xyz = tar.extractfile(xyz_name)
-        comp = Compound(xyz=xyz)
-        compounds.append(comp)
+    energies = np.array(energies)
 
-train_compounds = compounds[:training_set_size]
-test_compounds = compounds[training_set_size:]
+    compounds = []
+    with tarfile.open("../../tests/test_data/qm7.tar.gz") as tar:
+        for xyz_name in xyzs:
+            xyz = tar.extractfile(xyz_name)
+            comp = Compound(xyz=xyz)
+            compounds.append(comp)
 
-train_quantities = energies[:training_set_size]
-test_quantities = energies[training_set_size:]
+    train_compounds = compounds[:training_set_size]
+    test_compounds = compounds[training_set_size:]
 
-# NOTE: we can use shift_quantities=True, shifting the labels by their mean, but since in this example they are extensive that is not likely to make the results better.
-model = KRRModel(shift_quantities=False)
+    train_quantities = energies[:training_set_size]
+    test_quantities = energies[training_set_size:]
 
-model.train(training_compounds=train_compounds, training_quantities=train_quantities)
+    # NOTE: we can use shift_quantities=True, shifting the labels by their mean, but since in this example they are extensive that is not likely to make the results better.
+    CMCalc = CMCalculator(size=29)
+    model = KRRModel(shift_quantities=False, representation_function=CMCalc)
 
-print("Optimized sigma:", model.sigma)
-print("Optimized l2reg divided by average kernel element:", model.l2reg_diag_ratio)
+    model.train(training_compounds=train_compounds, training_quantities=train_quantities)
 
-predictions = model.predict_from_compounds(test_compounds)
-print("Prediction MAE:", MAE()(predictions - test_quantities))
-print("Test set quantity STD:", np.std(test_quantities))
+    print("Optimized sigma:", model.sigma)
+    print("Optimized l2reg divided by average kernel element:", model.l2reg_diag_ratio)
+
+    predictions = model.predict_from_compounds(test_compounds)
+    print("Prediction MAE:", MAE()(predictions - test_quantities))
+    print("Test set quantity STD:", np.std(test_quantities))
+
+
+if __name__ == "__main__":
+    main()

examples/models/ex_FCHL19_SORF_model.py

@@ -7,45 +7,59 @@
 from qml2 import Compound
 from qml2.models.loss_functions import MAE
 from qml2.models.sorf import SORFLocalModel
+from qml2.representations.calculators import FCHL19Calculator
 
-xyzs = []
-energies = []
 
-training_set_size = 501
-test_set_size = 1000
-num_mols = training_set_size + test_set_size
+def main():
+    xyzs = []
+    energies = []
 
-with open("../../tests/test_data/hof_qm7.txt") as csvfile:
-    reader = csv.reader(csvfile, delimiter=" ")
-    all_rows = list(reader)
-    random.shuffle(all_rows)
-    for row in all_rows[:num_mols]:
-        xyzs.append(row[0])
-        energies.append(float(row[1]))
+    training_set_size = 501
+    test_set_size = 1000
+    num_mols = training_set_size + test_set_size
 
-energies = np.array(energies)
+    with open("../../tests/test_data/hof_qm7.txt") as csvfile:
+        reader = csv.reader(csvfile, delimiter=" ")
+        all_rows = list(reader)
+        random.shuffle(all_rows)
+        for row in all_rows[:num_mols]:
+            xyzs.append(row[0])
+            energies.append(float(row[1]))
 
-compounds = []
-with tarfile.open("../../tests/test_data/qm7.tar.gz") as tar:
-    for xyz_name in xyzs:
-        xyz = tar.extractfile(xyz_name)
-        comp = Compound(xyz=xyz)
-        compounds.append(comp)
+    energies = np.array(energies)
 
-train_compounds = compounds[:training_set_size]
-test_compounds = compounds[training_set_size:]
+    compounds = []
+    with tarfile.open("../../tests/test_data/qm7.tar.gz") as tar:
+        for xyz_name in xyzs:
+            xyz = tar.extractfile(xyz_name)
+            comp = Compound(xyz=xyz)
+            compounds.append(comp)
 
-train_quantities = energies[:training_set_size]
-test_quantities = energies[training_set_size:]
+    train_compounds = compounds[:training_set_size]
+    test_compounds = compounds[training_set_size:]
 
-# using "shift_quantites=True" means using dressed atom approach; requires defining `possible_nuclear_charges` though.
-model = SORFLocalModel(shift_quantities=True, possible_nuclear_charges=np.array([1, 6, 7, 8, 16]))
+    train_quantities = energies[:training_set_size]
+    test_quantities = energies[training_set_size:]
 
-model.train(training_compounds=train_compounds, training_quantities=train_quantities)
+    possible_nuclear_charges = np.array([1, 6, 7, 8, 16])
+    FCHL19Calc = FCHL19Calculator(elements=possible_nuclear_charges)
+    # using "shift_quantites=True" means using dressed atom approach; requires defining `possible_nuclear_charges` though.
+    # in this example we will use FCHL19; note that it requires defining "elements" keyword argument defining nuclear charges that can be encountered in the chemical space of interest.
+    model = SORFLocalModel(
+        shift_quantities=True,
+        possible_nuclear_charges=possible_nuclear_charges,
+        representation_function=FCHL19Calc,
+    )
 
-print("Optimized sigma:", model.sigma)
-print("Optimized l2reg divided by average kernel element:", model.l2reg_diag_ratio)
+    model.train(training_compounds=train_compounds, training_quantities=train_quantities)
 
-predictions = model.predict_from_compounds(test_compounds)
-print("Prediction MAE:", MAE()(predictions - test_quantities))
-print("Test set quantity STD:", np.std(test_quantities))
+    print("Optimized sigma:", model.sigma)
+    print("Optimized l2reg divided by average kernel element:", model.l2reg_diag_ratio)
+
+    predictions = model.predict_from_compounds(test_compounds)
+    print("Prediction MAE:", MAE()(predictions - test_quantities))
+    print("Test set quantity STD:", np.std(test_quantities))
+
+
+if __name__ == "__main__":
+    main()