utils
- class Logger(filein, append, suffix='dat', verbose=True)
Wrapper class for file-based logging with console output.
Provides unified logging to both file and console. Messages are automatically appended with newlines and printed to stdout.
- Attributes:
log: File object for writing log messages (or empty string if verbose=False)
- finalize()
Close the log file.
Safely closes file handle. Does nothing if file logging is disabled.
- write(message)
Write message to log file and print to console.
Appends newline to message automatically. Prints to stdout regardless of file logging status.
- Args:
message (str): Text to log
- add_prefix_suffix(name, args)
Add prefix and/or suffix to filename.
- Args:
name (str): Base filename args: Arguments object with prefix and suffix attributes
- Returns:
str: Modified filename with prefix/suffix
- blocking_wrapper(func, *args, **kwargs)
Execute function and wait for any subprocess.Popen objects.
Ensures all subprocess.Popen objects returned by the function complete before returning. Useful for managing parallel processes.
- cclib_atoms_coords(cclib_data, geom)
Convert cclib atomic data to QPREP-compatible format.
Extracts atom types and coordinates from cclib parsed data.
- Args:
cclib_data (dict): Parsed data from cclib with 'atomnos' and 'atomcoords' geom (int): Geometry index to extract (-1 for last geometry)
- Returns:
- tuple: (atom_types, cartesians)
atom_types (list): Element symbols for each atom
cartesians (array): 3D coordinates for specified geometry
- check_crest(self)
Verify CREST is installed and accessible.
Attempts to run CREST help command. Exits with error if not found.
- Args:
self: Object with args.log for error reporting
- check_dependencies(self)
Check that all required dependencies are installed.
Validates OpenBabel, RDKit, and program-specific dependencies (xTB/CREST for quantum calculations, or torch/ASE/torchani for ANI).
- Args:
self: Arguments object with program settings and logger
- check_files(self, module)
Validate that input files exist and are accessible.
- Args:
self: Arguments object with files list and logger module (str): Module name for error messages
- check_run(w_dir)
Determine QCORR run folder and resume status.
Parses directory path to detect if this is a continuation of a failed run or a new run cycle. Used for QCORR workflow management.
- Args:
w_dir (Path): Working directory path to analyze
- Returns:
- tuple: (folder_count, resume_qcorr)
folder_count (int): Run number (1 for new, N+1 for failed run N)
resume_qcorr (bool): True if resuming from failed run
- check_version(self, program, version_line, target_version, n_split, install_cmd)
Verify program version compatibility with AQME.
Checks if installed xTB/CREST version is compatible. Allows versions up to 2-4 minor releases ahead of target.
- Args:
self: Object with args.log and args.initial_dir program (str): Program name ('xTB' or 'CREST') version_line (str): String to search for in version output target_version (str): Minimum required version n_split (int): Index of version number in split line install_cmd (str): Command to install correct version
- check_xtb(self)
Verify xTB is installed and accessible.
Attempts to run xTB help command. Exits with error if not found.
- Args:
self: Object with args.log for error reporting
- command_line_args()
Load command line arguments for AQME.
Parses arguments from sys.argv, converts them to appropriate types, and loads default values for unspecified parameters.
- Returns:
argparse.Namespace: Arguments object with all AQME parameters
- format_lists(value, arg_name)
Transform string arguments into lists.
Handles various input formats and removes extra spaces. Special handling for qdescp_atoms which uses different parsing.
- Args:
value (str or list): Input value to convert arg_name (str): Argument name for special handling
- Returns:
list: Formatted list of values
- get_conf_RMS(mol1, mol2, c1, c2, heavy, max_matches_rmsd)
Calculate RMSD between two molecule conformations.
Computes best RMSD by aligning mol1 to mol2. Note: mol1 is modified (left in aligned state) unless heavy=True.
- Args:
mol1 (rdkit.Chem.Mol): Probe molecule to align mol2 (rdkit.Chem.Mol): Target molecule for alignment c1 (int): Conformer ID of mol1 (-1 for default) c2 (int): Conformer ID of mol2 (-1 for default) heavy (bool): If True, ignore hydrogens in RMSD calculation max_matches_rmsd (int): Maximum substructure matches to consider
- Returns:
float: Best RMSD value found (Angstroms)
- Note:
numThreads must be 1 to not overload the multithreading
- get_files(value)
Process and expand file path specifications.
Handles wildcards, list parsing, and path resolution. Converts relative paths to absolute and expands glob patterns.
- Args:
value (str or list): File path(s), potentially with wildcards
- Returns:
list: Expanded list of absolute file paths
- get_info_input(file)
Extract coordinates and charge from quantum chemistry input files.
Supports Gaussian (.com, .gjf) and ORCA (.inp) file formats.
Parameters
- filestr or pathlib.Path
Path to a valid .com, .gjf, or .inp file
Returns
- coordinateslist
List of strings (without n) containing xyz coordinates
- chargestr
Total charge of the system
- multstr
Spin multiplicity of the system
- load_from_yaml(self)
Load calculation parameters from YAML file.
Updates self attributes with values from YAML file if varfile is specified. Handles file validation and error reporting.
- Args:
self: Arguments object with varfile attribute
- Returns:
tuple: (self, txt_yaml) - updated args and status message
- load_sdf(input_file, keep_xyz=False)
Load molecules from SDF file with error recovery.
Attempts to load SDF file. If loading fails (e.g., from GaussView), uses OpenBabel to repair the file. If that fails, converts via XYZ.
- Args:
input_file (str): Path to SDF file keep_xyz (bool): Keep XYZ input
- Returns:
list: RDKit molecule objects with hydrogens preserved
- load_variables(kwargs, aqme_module, create_dat=True)
Load default and user-defined variables for AQME modules.
Combines default values, user-specified values, and YAML file parameters. Sets up working directories and creates log files.
- Args:
kwargs (dict): User-defined arguments aqme_module (str): Name of AQME module (csearch, cmin, qprep, etc.) create_dat (bool): Whether to create log file
- Returns:
argparse.Namespace: Complete arguments object with all parameters
- mol_from_sdf_or_mol_or_mol2(input_file, module, args, low_check=None, keep_xyz=False)
Load molecule objects from SDF, MOL, or MOL2 files.
Handles different file formats and modules (qprep, cmin, csearch). For qprep/cmin, can filter conformers by count or energy window.
Parameters
- input_filestr
Path to input file (SDF, MOL, or MOL2)
- modulestr
AQME module name ('qprep', 'cmin', or 'csearch')
- argsargparse.Namespace
Arguments object with charge/mult settings
- low_checkstr, int, float, or None
Filtering criterion: - 'lowest_only': Return only lowest energy conformer - int: Return first N conformers - float: Return conformers within energy window (kcal/mol) - None: Return all conformers
- keep_xyzbool
Keep the generated XYZ for CREST runs in CSEARCH when using an XYZ input
Returns
- For qprep/cmin:
list: Molecule objects (optionally filtered)
- For csearch:
tuple: (suppl, charges, mults, IDs)
- move_file(destination, source, file)
Move file from source to destination folder.
Creates destination directory if it doesn't exist. Replaces file if it already exists at destination.
- Args:
destination (Path): Destination folder path source (Path): Source folder path file (str): Filename (including extension)
- periodic_table()
Generate periodic table as a list of element symbols.
Creates a list where the index corresponds to atomic number. Index 0 is empty string, index 1 is 'H', index 2 is 'He', etc.
- Returns:
list: Element symbols indexed by atomic number (0-118)
- read_file(initial_dir, w_dir, file)
Read file and return all lines.
Changes to working directory, reads file, then returns to initial directory.
- Args:
initial_dir (Path): Directory to return to after reading w_dir (Path): Directory containing the file file (str): Filename to read
- Returns:
list: Lines from the file (including newline characters)
- read_xyz_charge_mult(file)
Extract charge and multiplicity from XYZ file title line.
Searches for charge=X and mult=Y keywords in XYZ title lines. Example: "FILENAME charge=1 mult=1 Eopt -129384.564"
- Args:
file (str or Path): Path to XYZ file
- Returns:
- tuple: (charge_xyz, mult_xyz)
charge_xyz (int): Molecular charge (default: 0)
mult_xyz (int): Spin multiplicity (default: 1)
- run_command(command, outfile, cwd=None, env=None)
Run subprocess command and save output to file.
Executes a command in a subprocess and redirects stdout to a file. Stderr is suppressed. The command runs without showing terminal output.
- Args:
command (list): Command and arguments to execute outfile (str): Path to output file for stdout cwd (str or Path, optional): Working directory for command execution env (dict, optional): Environment variables for subprocess
- set_destination(self, module)
Set up the destination folder for output files.
Uses destination argument if provided, otherwise creates folder in initial directory named after the module.
- Args:
self: Arguments object with destination settings module (str): Module name (CSEARCH, CMIN, etc.)
- Returns:
pathlib.Path: Destination folder path