from abc import ABC, abstractmethod
from typing import Dict, Any, Union
import numpy as np
[docs]
class QuantumEngine(ABC):
"""
Abstract interface for quantum chemistry orcale engines.
Defines the lifecycle of a single calculation.
Any new QC software connector must inherit from this class and implement its
abstract methods.
"""
[docs]
def evaluate(
self,
geometry: Union[str, tuple],
fidelity_params: Dict[str, Any],
work_dir: str,
clean=True,
return_outs=True,
) -> Dict[str, Any]:
"""
The main method called by the Active Learning loop.
This method handles the entire lifecycle of a quantum chemistry calculation:
generating the input, running the engine, parsing the results, and
optionally cleaning up scratch files.
Parameters
----------
geometry : str or tuple
The molecular geometry. Can be a filepath to an XYZ file (str)
or a tuple of (Z, R) coordinate arrays.
fidelity_params : dict
A dictionary of engine-specific parameters for this fidelity
level (e.g., basis set, functional, convergence criteria).
work_dir : str
The directory where temporary input/output files should be written.
clean : bool, optional
If True, calls the `cleanup` method after parsing to delete
heavy scratch/temporary files. Default is True.
return_outs : bool, optional
If True, returns the parsed results dictionary. Default is True.
Returns
-------
dict or None
A dictionary of parsed properties (e.g., energies, gradients, success flag)
if `return_outs` is True. Otherwise, returns None.
"""
input_file = self.generate_input(geometry, fidelity_params, work_dir)
output_file = self.run_calculation(input_file, work_dir)
results = self.parse_output(output_file)
if clean:
self.cleanup(work_dir)
if return_outs:
return results
else:
pass
[docs]
@abstractmethod
def run_calculation(self, input_file: str, work_dir: str) -> str:
"""
Executes the quantum chemistry program.
This method should handle subprocess calls, error catching for
crashes, and environment variable setup required by the QC engine.
Parameters
----------
input_file : str
The path to the input file generated by `generate_input`.
work_dir : str
The directory where the calculation is being executed.
Returns
-------
str
The path to the primary output/log file generated by the engine.
"""
pass
[docs]
@abstractmethod
def parse_output(self, output_file: str) -> Dict[str, Any]:
"""
Parses the output file to extract chemical properties.
Parameters
----------
output_file : str
The path to the primary output file returned by `run_calculation`.
Returns
-------
dict
A dictionary containing the extracted properties.
MUST contain at least a 'success': bool key indicating if the
calculation terminated normally without crashing.
"""
pass
[docs]
@abstractmethod
def cleanup(self, work_dir: str):
"""
Removes temporary/scratch files to save disk space.
This method is called automatically by `evaluate` if `clean=True`.
It should safely attempt to delete massive or unnecessary files
(like wavefunctions, heavy integrals, or checkpoint files)
while leaving the main output log intact.
Parameters
----------
work_dir : str
The directory where the calculation was executed.
"""
pass