'''
.. code-block::
!---------------------------------------------------------------------------!
! aiqm3: Artificial Intelligence-Enhanced Quantum Mechanical Method 3 !
! Implementations by: Yuxinxin Chen and !
! Pavlo O. Dral !
!---------------------------------------------------------------------------!
The AIQM3 weights are fetched at first use from Zenodo record 15876694; their
own terms apply. Cite Y. Chen, Y.-F. Hou, R. Zubatyuk, O. Isayev, P.O. Dral,
J. Chem. Theory Comput. 2026, 22, 2232.
'''
import os
import sys
import json
from . import dispersion as dispersion_utils
from . import delta_learning
from .model_cls import method_model, model_tree_node, downloadable_model
from .interfaces.torchani_interface import ani
[docs]
class aiqm3(method_model, downloadable_model):
"""
GFN2-xTB based artificial intelligence quantum-mechanical method 3 (AIQM3)
Arguments:
method (str, optional): Currently supports AIQM3, AIQM3@DFT, AIQM3@DFT*. Default: AIQM3
working_directory (str, optional): The path to save temporary calculation file. By default, current directory will be choosed.
baseline_kwargs (dict, optional): Keywords passed to GFN2-xTB. Default: None
dispersion_kwargs (dict, optional): keywords passed to dftd3. Default: None
nthreads (int, optional): The number of threads to be used. Default: None
.. code-block::
# Initialize molecule
mol = ml.data.molecule()
mol.read_from_xyz_file(filename='ethanol.xyz')
# Run AIQM3 calculation
aiqm3 = ml.methods(method='aiqm3')
aiqm3.predict(molecule=mol, calculate_energy=True, calculate_energy_gradients=True, calculate_hessian=True)
# Get energy, gradient, and uncertainty of AIQM3
energy = mol.energy
gradient = mol.get_energy_gradients()
hess = mol.hessian
std = mol.aiqm3_nn.energy_standard_deviation
Molecules containing elements outside the set the model was trained on cannot
be treated by AIQM3 itself. Models covering more elements include the Aitomic
add-ons (for example AIQM4@DFT) and AIQM3@UAIQM, the UAIQM extension of this
model, which can be used out of the box for them; only elements that GFN2-xTB
itself cannot describe are out of reach. The add-ons, including the UAIQM
models, are installed separately (http://MLatom.com/aitomic). Specify the
model version explicitly:
.. code-block:: python
uaiqm = ml.models.methods(method='uaiqm_gfn2xtbstar@cc', version='20250115')
.. code-block:: bash
mlatom sp uaiqm_gfn2xtbstar@cc uversion=20250115 xyzfile=mol.xyz
"""
supported_methods = ['AIQM3', 'AIQM3@DFT', 'AIQM3@DFT*']
_tl = True
verbose = 1
def __init__(
self,
method: str = 'AIQM3',
working_directory: str = None,
baseline_kwargs: dict = None,
dispersion_kwargs: dict = None,
nthreads: int = 1,
model_index = None,
device = None,
):
import torch
if device is None:
device = 'cuda' if torch.cuda.is_available() else 'cpu'
self.device = torch.device(device)
self.method = method.lower()
self.model_name = self.method.replace('@','at')
if model_index is None:
self.model_index = [ii for ii in range(8)]
elif isinstance(model_index, list):
self.model_index = model_index
elif isinstance(model_index, int):
self.model_index = [model_index]
else:
raise ValueError(f"Unrecognized model_index type: {type(model_index)}. Please provide int, list or None.")
if baseline_kwargs is None: self.baseline_kwargs = {}
else: self.baseline_kwargs = baseline_kwargs
# ``None`` -> the model's own dispersion term, D3(BJ)/b973c for AIQM3 and
# none for AIQM3@DFT*. ``False`` switches it off; ``{}`` raises. The
# stored spec identifies the term only; where it runs is decided when the
# node is built, so an unrelated argument can never turn it on or off.
if dispersion_kwargs is None:
self.dispersion_kwargs = dispersion_utils.native_dispersion_kwargs(self.method)
else:
self.dispersion_kwargs = dispersion_utils.normalize(dispersion_kwargs)
self._working_directory = None
if working_directory is not None:
self.set_working_directory(working_directory)
self._load_pretrained_models()
self.nthreads = nthreads
@property
def nthreads(self):
return self._nthreads
@nthreads.setter
def nthreads(self, value):
self._nthreads = value
self.aiqm3_model.nthreads = self._nthreads # nthreads can be directly assigned to each tree node
@property
def working_directory(self):
return self._working_directory
@working_directory.setter
def working_directory(self, value):
self._working_directory = value
self.set_working_directory(value)
self.reload_baseline(); self.reload_dispersion()
self.reload()
def set_working_directory(self, working_directory):
self._working_directory = working_directory
self.baseline_kwargs["working_directory"] = os.path.join(os.path.abspath(working_directory), "_baseline")
def dispersion_working_directory(self):
if self._working_directory is None:
return None
return os.path.join(os.path.abspath(self._working_directory), "_dispersion")
def reload_baseline(self):
from .models import methods
self.baseline = model_tree_node(
name='gfn2xtbstar',
model=methods(method='GFN2-xTB*', **self.baseline_kwargs),
operator='predict'
)
def reload_dispersion(self):
self.d3 = dispersion_utils.build_node(
self.dispersion_kwargs, name='d3b973c',
working_directory=self.dispersion_working_directory())
def reload(self):
children = [self.baseline, self.nn]
if self.d3 is not None:
children.append(self.d3)
self.aiqm3_model = model_tree_node(
name=self.model_name,
children=children,
operator='sum'
)
[docs]
def predict(
self,
molecular_database=None,
molecule=None,
calculate_energy=True,
calculate_energy_gradients=False,
calculate_hessian=False,
calculate_dipole_derivatives=False,
):
molDB = super().predict(molecular_database=molecular_database, molecule=molecule)
for mol in molDB.molecules:
self.predict_for_molecule(molecule=mol,
calculate_energy=calculate_energy, calculate_energy_gradients=calculate_energy_gradients, calculate_hessian=calculate_hessian,
calculate_dipole_derivatives=calculate_dipole_derivatives)
def predict_for_molecule( # no specific treatment to atomic energies currently
self,
molecule=None,
calculate_energy=True,
calculate_energy_gradients=False,
calculate_hessian=False,
calculate_dipole_derivatives=False,
):
supported_elements = self._supported_element_symbols()
from . import data
unsupported = sorted({
data.atomic_number2element_symbol.get(atom.atomic_number, str(atom.atomic_number))
for atom in molecule.atoms
} - set(supported_elements))
if unsupported:
errmsg = (
' * Error * Molecule contains elements outside the set this AIQM3 model was '
'trained on: %s. Supported elements: %s. No calculations performed.\n'
' To treat these elements, use a model that covers them:\n'
' - the Aitomic add-ons may contain models trained on more elements\n'
' (for example AIQM4@DFT);\n'
' - AIQM3@UAIQM, the UAIQM extension of this model, can be used out of\n'
' the box for these elements; only elements that GFN2-xTB cannot\n'
' describe are out of reach.\n'
' The add-ons, including the UAIQM models, are installed separately; see\n'
' http://MLatom.com/aitomic. Choose the model version explicitly\n'
' (\'newest\' is the default); e.g.:\n'
' Python: ml.models.methods(method=\'uaiqm_gfn2xtbstar@cc\', version=\'20250115\')\n'
' CLI: mlatom sp uaiqm_gfn2xtbstar@cc uversion=20250115 xyzfile=mol.xyz'
% (', '.join(unsupported), ', '.join(supported_elements)))
raise ValueError(errmsg)
self.aiqm3_model.predict(
molecule=molecule,
calculate_energy=calculate_energy, calculate_energy_gradients=calculate_energy_gradients, calculate_hessian=calculate_hessian,
calculate_dipole_derivatives=calculate_dipole_derivatives,
)
molecule.__dict__[f'{self.model_name}_nn'].standard_deviation(properties=['energy'])
[docs]
def _supported_element_symbols(self):
"""The elements this model can treat: its weights' species, or the published set."""
symbols = getattr(self, 'element_symbols_available', None)
if symbols:
return list(symbols)
return ['H', 'C', 'N', 'O', 'F', 'S', 'Cl']
def _load_pretrained_models(self):
model_paths = self.get_model_paths()
self.reload_baseline()
self.reload_dispersion()
self.nn = model_tree_node(
name=f'{self.model_name}_nn',
children=[
model_tree_node(
name=f'{self.model_name}_nn{self.model_index[ii]}',
model=ani(
model_file=model_paths[self.model_index[ii]],
device=self.device, verbose=0),
operator='predict'
) for ii in range(len(self.model_index))
],
operator='average'
)
self.element_symbols_available = self.nn.children[0].model.species_order
self.aiqm3_model = model_tree_node(
name=self.model_name,
children=[self.baseline, self.nn, self.d3] if self.d3 is not None else [self.baseline, self.nn],
operator='sum'
)
def get_model_paths(self):
if self.model_name.lower() == 'aiqm3':
download_links = [
'https://zenodo.org/records/15876694/files/aiqm3_cc_model.zip?download=1',
'https://aitomistic.xyz/model/uaiqm_gfn2xtbstar_cc_20250115.zip']
model_dir = 'aiqm3_model'
model_files = [f'cv{ii}.pt' for ii in range(8)]
elif self.model_name.lower() in ['aiqm3atdft', 'aiqm3atdft*']:
download_links = [
'https://zenodo.org/records/15876694/files/aiqm3_dft_model.zip?download=1',
'https://aitomistic.xyz/model/uaiqm_gfn2xtbstar_dft_20240619.zip']
model_dir = 'aiqm3_dft_model'
model_files = [f'cv{ii}.pt' for ii in range(8)]
else:
raise ValueError(f'Unsupported AIQM3 method: {self.model_name}')
mlatom_model_dir, to_download = self.check_model_path(model_dir, model_files)
if to_download: self.download(download_links, mlatom_model_dir)
model_paths = [os.path.join(mlatom_model_dir, model_files[ii]) for ii in range(8)]
return model_paths
# ------------------------------------------------------------------
# Transfer-learning API
# ------------------------------------------------------------------
def _prepare_delta_database(
self,
target_db,
property_to_learn,
xyz_derivative_property_to_learn=None,
verbose=0,
):
from . import data
delta_db = data.molecular_database()
for mol in target_db.molecules:
delta_mol = mol.copy(atomic_labels=['xyz_coordinates'])
delta_mol.__dict__['target_energy'] = mol.__dict__[property_to_learn]
if xyz_derivative_property_to_learn:
delta_mol.__dict__['target_grad'] = mol.get_xyz_vectorial_properties(xyz_derivative_property_to_learn)
delta_db.append(delta_mol)
self.baseline.predict(
molecular_database=delta_db,
calculate_energy=True,
calculate_energy_gradients=bool(xyz_derivative_property_to_learn),
)
for mol in delta_db.molecules:
baseline_energy = mol.gfn2xtbstar.energy
mol.delta_energy = mol.target_energy - baseline_energy
if xyz_derivative_property_to_learn:
baseline_grad = mol.gfn2xtbstar.energy_gradients
delta_grad = mol.target_grad - baseline_grad
mol.add_xyz_vectorial_property(delta_grad, 'delta_energy_gradients')
return delta_db
def train(self, **kwargs):
# default settings
kwargs['save_model'] = True
kwargs['reset_parameters'] = False
kwargs['reset_network'] = True # rebuild around them; the data may add elements
kwargs['reset_aev'] = True
kwargs['reset_optimizer'] = True
kwargs['reset_energy_shifter'] = True
file_to_save_model = kwargs.pop('file_to_save_model', None)
verbose = kwargs.get('verbose', 0)
# The dispersion term named here is subtracted from the reference labels
# AND added back at prediction - the same term on both sides. No default
# where the model has a native term; the declaration comes from
# dispersion_kwargs= or from a prepared delta_db='s provenance stamp.
tl_dispersion_kwargs = kwargs.pop('dispersion_kwargs', 'not given')
property_to_learn = kwargs.get('property_to_learn', 'energy')
xyz_derivative_property_to_learn = kwargs.get('xyz_derivative_property_to_learn', None)
resolved = delta_learning.resolve_training_labels(
model_method=self.method,
molecular_database=kwargs.get('molecular_database', None),
delta_db=kwargs.pop('delta_db', None),
# Reusing an already-computed baseline is what makes trying a second
# dispersion choice on the same geometries free; it accepts a prepared
# database and takes the component out of it by name.
baseline_db=kwargs.pop('baseline_db', None),
dispersion_db=kwargs.pop('dispersion_db', None),
dispersion_kwargs=tl_dispersion_kwargs,
baseline_method='GFN2-xTB*',
baseline_kwargs=self.baseline_kwargs,
property_to_learn=property_to_learn,
xyz_derivative_property_to_learn=xyz_derivative_property_to_learn,
working_directory=self.working_directory,
verbose=verbose,
)
self.dispersion_kwargs = resolved['dispersion_kwargs']
self._training_database = resolved['database']
self._training_delta_source = resolved['delta_source']
self._training_stamp = resolved['stamp']
delta_db = resolved['database']
kwargs['molecular_database'] = delta_db
kwargs['property_to_learn'] = 'delta_energy'
if xyz_derivative_property_to_learn:
kwargs['xyz_derivative_property_to_learn'] = 'delta_energy_gradients'
if 'hyperparameters' in kwargs:
_hyperparameters = kwargs['hyperparameters']
else:
_hyperparameters = {}
# default hyperparameters
if 'fixed_layers' not in _hyperparameters:
_hyperparameters['fixed_layers'] = [[0,4]]
if 'loss_type' not in _hyperparameters:
_hyperparameters['loss_type'] = 'geometric'
if 'max_epochs' not in _hyperparameters:
_hyperparameters['max_epochs'] = 100
# Remove loaded model
del self.nn
del self.aiqm3_model
# Load pretrained models
model_paths = self.get_model_paths()
pretrained_models = [ani(model_file=model_paths[self.model_index[ii]], device=self.device, verbose=verbose) for ii in range(len(self.model_index))]
# reload aev parameters
for aev_param in ['Rcr','Rca','EtaR','ShfR','Zeta','ShfZ','EtaA','ShfA']:
if aev_param not in _hyperparameters:
try:
_hyperparameters[aev_param] = pretrained_models[0].aev_computer._buffers[aev_param].reshape(-1,)
except:
_hyperparameters[aev_param] = pretrained_models[0].aev_computer.__dict__[aev_param]
kwargs['hyperparameters'] = _hyperparameters
retrained_models = []
modelname = self.model_name
save_dir = file_to_save_model if file_to_save_model else f'{modelname}_retrained'
os.makedirs(save_dir, exist_ok=True)
for ii, pmodel in enumerate(pretrained_models):
print(f'\nStart retraining on model {self.model_index[ii]}...')
sys.stdout.flush()
kwargs['file_to_save_model'] = os.path.join(save_dir, f'cv{self.model_index[ii]}.pt')
pmodel.element_symbols_available = self.element_symbols_available
pmodel.train(**kwargs)
retrained_models.append(pmodel)
self.nn = model_tree_node(
name=f'{self.model_name}_nn',
children=[
model_tree_node(
name=f'{self.model_name}_nn{self.model_index[ii]}',
model=pretrained_models[ii],
operator='predict'
) for ii in range(len(self.model_index))
],
operator='average'
)
self.reload_baseline()
self.reload_dispersion()
self.reload()
self.element_symbols_available = retrained_models[0].species_order
self._training_databases = delta_learning.write_training_database(
self._training_database, save_dir,
delta_source=self._training_delta_source, verbose=verbose)
self.energy_expression = delta_learning.report_model_composition(
baseline='GFN2-xTB*', neural_network='dNN',
dispersion_kwargs=self.dispersion_kwargs, verbose=verbose)
# Leave a directory that can be loaded back, rather than one holding
# weights that only become a model after a separate save() call.
self.save(save_dir)
[docs]
def _iter_ani_leaves(self, node=None):
"""
Iterate over the ``ani`` leaf models inside the AIQM3 model tree.
"""
if node is None:
node = self.aiqm3_model
if node.model is not None and isinstance(node.model, ani):
try:
cv_index = int(node.name.split('nn')[-1])
except (ValueError, IndexError):
cv_index = 0
yield node, cv_index
if node.children:
for child in node.children:
yield from self._iter_ani_leaves(child)
[docs]
@staticmethod
def _resolve_model_paths(model_dict, base_dir):
"""Recursively resolve relative ``model_file`` paths."""
if not isinstance(model_dict, dict):
return
if model_dict.get('type') == 'ml_model' and 'kwargs' in model_dict:
kwargs = model_dict['kwargs']
if 'model_file' in kwargs:
model_file = kwargs['model_file']
if not os.path.isabs(model_file):
kwargs['model_file'] = os.path.normpath(os.path.join(base_dir, model_file))
for child in model_dict.get('children') or []:
aiqm3._resolve_model_paths(child, base_dir)
model = model_dict.get('model')
if model:
aiqm3._resolve_model_paths(model, base_dir)
[docs]
@staticmethod
def _make_paths_relative(model_dict, base_dir):
"""Recursively make ``model_file`` paths relative to ``base_dir``."""
if not isinstance(model_dict, dict):
return
if model_dict.get('type') == 'ml_model' and 'kwargs' in model_dict:
kwargs = model_dict['kwargs']
if 'model_file' in kwargs:
model_file = kwargs['model_file']
if os.path.isabs(model_file):
kwargs['model_file'] = os.path.relpath(model_file, base_dir)
for child in model_dict.get('children') or []:
aiqm3._make_paths_relative(child, base_dir)
model = model_dict.get('model')
if model:
aiqm3._make_paths_relative(model, base_dir)
[docs]
def save(self, model_file: str = '') -> None:
"""Save the transfer-learned AIQM3 model to a directory."""
if not model_file:
model_file = f'{self.model_name}_tl_model'
os.makedirs(model_file, exist_ok=True)
base_dir = os.path.abspath(model_file)
# Save each ani leaf as cv{i}.pt
for node, cv_index in self._iter_ani_leaves():
pt_path = os.path.join(base_dir, f'cv{cv_index}.pt')
node.model.save(pt_path)
node.model.model_file = pt_path
# Build a model tree dict with relative paths
model_tree_dict = self.aiqm3_model.dump(format='dict')
self._make_paths_relative(model_tree_dict, base_dir)
tree = {
'type': 'aiqm3',
'module': {
'name': self.__module__,
'path': sys.modules[self.__module__].__spec__.origin,
},
'tl': True,
'method': self.method,
'model_index': self.model_index,
'device': str(self.device) if hasattr(self, 'device') else 'cpu',
'element_symbols_available': self.element_symbols_available,
'baseline_kwargs': self.baseline_kwargs,
'dispersion_kwargs': self.dispersion_kwargs,
'energy_expression': getattr(self, 'energy_expression', None),
'training_labels': getattr(self, '_training_databases', None),
'provenance': getattr(self, '_training_stamp', None),
'working_directory': self.working_directory if hasattr(self, '_working_directory') else None,
'model_tree': model_tree_dict,
}
tree_path = os.path.join(base_dir, 'tree.json')
with open(tree_path, 'w') as f:
json.dump(tree, f, indent=4)
if self.verbose:
print(f'AIQM3 TL model saved in {base_dir}')
[docs]
@classmethod
def load(cls, model_file: str, device=None):
"""Load a transfer-learned AIQM3 model from a directory or ``tree.json``."""
if os.path.isdir(model_file):
tree_file = os.path.join(model_file, 'tree.json')
else:
tree_file = model_file
if not os.path.isfile(tree_file):
raise FileNotFoundError(f'Cannot find tree.json at {tree_file}')
with open(tree_file) as f:
model_dict = json.load(f)
base_dir = os.path.dirname(os.path.abspath(tree_file))
if device is None and 'device' in model_dict:
device = model_dict['device']
return cls.from_dict(model_dict, device=device, base_dir=base_dir)
[docs]
@classmethod
def from_dict(cls, model_dict, device=None, base_dir=None):
"""Reconstruct an ``aiqm3`` instance from a dictionary produced by :meth:`save`."""
import torch
instance = cls.__new__(cls)
if device is None:
device = 'cuda' if torch.cuda.is_available() else 'cpu'
instance.device = torch.device(device)
instance.method = model_dict['method']
instance.model_name = instance.method.lower().replace('@', 'at')
instance.model_index = model_dict.get('model_index', [ii for ii in range(8)])
instance._tl = True
instance.verbose = 1
instance.element_symbols_available = model_dict.get('element_symbols_available', [])
instance.baseline_kwargs = dict(model_dict.get('baseline_kwargs', {}))
instance.dispersion_kwargs = model_dict.get('dispersion_kwargs', None)
instance._working_directory = None
if model_dict.get('working_directory') is not None:
instance._working_directory = model_dict['working_directory']
instance.baseline_kwargs['working_directory'] = os.path.join(os.path.abspath(instance._working_directory), '_baseline')
instance.baseline_kwargs['working_directory'] = os.path.join(
os.path.abspath(instance._working_directory), '_baseline')
if base_dir is not None:
cls._resolve_model_paths(model_dict['model_tree'], base_dir)
for child in model_dict['model_tree']['children'][1]['children']:
child['model']['kwargs']['device'] = str(instance.device)
from .models import load_dict
instance.aiqm3_model = load_dict(model_dict['model_tree'], base_dir=base_dir)
instance.baseline = instance.aiqm3_model.children[0]
instance.nn = instance.aiqm3_model.children[1]
instance.energy_expression = model_dict.get('energy_expression', None)
instance._training_databases = model_dict.get('training_labels', None)
instance._training_stamp = model_dict.get('provenance', None)
# Find the dispersion node by name, not by position.
instance.d3 = None
for child in instance.aiqm3_model.children:
if getattr(child, 'name', '') == 'dispersion':
instance.d3 = child
instance.nthreads = 1
return instance