CLIFF API Documentation

• cliff.helpers package
  • Submodules
  • cliff.helpers.cell module
  • cliff.helpers.constants module
  • cliff.helpers.options module
  • cliff.helpers.system module
  • cliff.helpers.utils module
  • Module contents

Driver Functions

Driver functions contain the main functions for energy computation, in addition to related functions needed for predicting atomic properties.

cliff.driver.dispersion_energy(dimers, ml_type='KRR', load_path=None, return_pairs=False, infile=None, options=None)

cliff.driver.electrostatic_energy(dimers, ml_type='KRR', load_path=None, return_pairs=False, infile=None, options=None)

cliff.driver.energy_kernel(mon_a, mon_b, options, return_pairs=False)

cliff.driver.exchange_energy(dimers, ml_type='KRR', load_path=None, return_pairs=False, infile=None, options=None)

cliff.driver.fill_monomer_lists(d_list, options, ml_type, load_path)

cliff.driver.induction_energy(dimers, ml_type='KRR', load_path=None, return_pairs=False, infile=None, options=None)

cliff.driver.load_atomic_properties(mol, path)

Loads Hirshfeld ratios, valence widths, and multipoles from files and stores them in the input System object. The System object finds the appropriate

cliff.driver.load_dimer_xyz(xyz_file, units='angstrom')

Loads a dimer xyz file, where the separation between dimers is specified as the last field in the second line in the file.

Parameters

• xyz_file (str) – Filename of the dimer xyz file. See main docs for how to format a dimer xyz.

• units (str:) – Units of the input coordinates, default to Angstrom. See QCElemental documentation for all available units.

Returns

dimer – QCElemental Molecule object. The returned Molecule object has two defined fragemens, one for each monomer.

Return type

molecule

cliff.driver.load_krr_models(options)

cliff.driver.load_monomer_xyz(xyz_file, units='angstrom')

Loads single/multi xyz file of monomers. Total charge is last field in comment line.

Function returns list of qcel Molecule objects.

Parameters

• xyz_file – Single xyz file containing one or more monomer coordinates. Each monomer is in the usual xyz format, with the exception that here we reqiure the second line to specify the total charge as the final field in a comma-separated list with potentially other information before.

• units (str:) – Units of the input coordinates, default to Angstrom. See QCElemental documentation for all available units.

Returns

molecules – A List of QCElemental molecule objects, each corresponding to a monomer in the input monomer xyz file.

Return type

list of qcelemental.molecule objects

cliff.driver.mol_to_sys(mol, options)

Converts a qcelemental Molecule into a System object used by CLIFF. The input molecule object can specify either a dimer or a monomer, though it has to have a name (mol.name) in either case.

Parameters

• mol – Input QCElemental molecule.

• options – Options object

Returns

systems – Cliff System object

Return type

cliff.System

cliff.driver.predict_atomic_properties(mol, models)

Predicts the atomic properties for an input System Returns System with Hirshfeld, atomic density, and multipole.

Parameters

• mol – Input System

• models (list of Hirshfeld ,`~cliff.atomic_properties.AtomicDensity`, and ~cliff.atomic_properties.Multipole) – List of dimension (3,) in the exact order: [Hirshfeld, AtomicDensity, Multipole].

cliff.driver.predict_from_dimers(dimers, ml_type='KRR', load_path=None, return_pairs=False, infile=None, options=None)

Compute energy components from a list of dimers. Uses all default options, turns off logging

Parameters

• dimers (qcel Molecule class or list of Molecule class) –

• return_pairs (bool to control returning of full atom-pairwise decomposition) –

cliff.driver.predict_from_monomer_list(monomer_a, monomer_b, ml_type='KRR', load_path=None, return_pairs=False, infile=None, options=None)

Compute energy components from two lists of monomers Uses default options, places mon_a in outer loop monomer list to outer loop

Parameters

• mon_a (list of (or single) qcel Molecules) –

• mon_b (list of (or single) qcel Molecules) –

• return_pairs (bool to control returning of full atom-pairwise decomposition) –

cliff.driver.save_atomic_properties(mol, path)

Saves atomic properties to a .npy file in a specified location. The name of the file is determined by the name of the original qcelemental Molecule object, with the suffix -h.npy, -vw.npy, or -mtp.npy for a given atomic property.

Parameters

• mol – System object with one or more atomic property fields already computed.

• path – Path to the destination where atomic property files are to be stored. Note that this path needs to exist, and it cannot be used to specify a filename.

cliff.driver.set_nthread(nthread)

Sets the number of threads used by the entire CLIFF module. Increasing threads can only impact any threaded numpy routines.

Parameters

nthread – Number of threads.

Return type

void

Fitting Functions

train.py Component-based Learned Intermolecular Force Field

Functions for fitting global parameters

cliff.fit.fit_disp_global_parameters(pathname, ref_dict, initial_guess=None, method='bfgs')

Fit dispersion coefficients

Parameters

• pathname – Path to the dimer xyz files. The comment (second) line in the xyz needs to specify the number of atoms in the first monomer.

• ref_dict – Dictionary containing the reference energies for fitting. The keys to the dictionary need to be the dimer filenames, and the value is a numpy array of energies: [total, elst, exch, indu].

• initial_guess – Numpy array of initial guess parameters (69 total). See the get_energy function for how initial parameters should be ordered. Default is 1.0 for all parameters

• gamma – Gamma parameter between 0 and 1.0 that controls the degree to which the total energy influences fitting.

• method – Algorithm used for minimization. See scipy.minimize documentation for all options

cliff.fit.fit_elst_global_parameters(pathname, ref_dict, initial_guess=None, method='bfgs')

Fit exponents used in electrostatics model

Parameters

• pathname – Path to the dimer xyz files. The comment (second) line in the xyz needs to specify the number of atoms in the first monomer.

• ref_dict – Dictionary containing the reference energies for fitting. The keys to the dictionary need to be the dimer filenames, and the value is a numpy array of energies: [total, elst, exch, indu].

• initial_guess – Numpy array of initial guess parameters (69 total). See the get_energy function for how initial parameters should be ordered. Default is 1.0 for all parameters

• gamma – Gamma parameter between 0 and 1.0 that controls the degree to which the total energy influences fitting.

• method – Algorithm used for minimization. See scipy.minimize documentation for all options

cliff.fit.fit_exch_global_parameters(pathname, ref_dict, initial_guess=None, method='bfgs')

Fit exchange coefficients

Parameters

• pathname – Path to the dimer xyz files. The comment (second) line in the xyz needs to specify the number of atoms in the first monomer.

• ref_dict – Dictionary containing the reference energies for fitting. The keys to the dictionary need to be the dimer filenames, and the value is a numpy array of energies: [total, elst, exch, indu].

• initial_guess – Numpy array of initial guess parameters (69 total). See the get_energy function for how initial parameters should be ordered. Default is 1.0 for all parameters

• gamma – Gamma parameter between 0 and 1.0 that controls the degree to which the total energy influences fitting.

• method – Algorithm used for minimization. See scipy.minimize documentation for all options

cliff.fit.fit_global_parameters(pathname, ref_dict, initial_guess=None, gamma=0.4, method='bfgs')

Fits global parameters used in CLIFF

Parameters

• pathname – Path to the dimer xyz files. The comment (second) line in the xyz needs to specify the number of atoms in the first monomer.

• ref_dict – Dictionary containing the reference energies for fitting. The keys to the dictionary need to be the extension-less dimer filenames, and the value is a numpy array of energies: [total, elst, exch, indu, disp].

• initial_guess – Numpy array of initial guess parameters (69 total). See the get_energy function for how initial parameters should be ordered. Default is 1.0 for all parameters

• gamma – Gamma parameter between 0 and 1.0 that controls the degree to which the total energy influences fitting.

• method – Algorithm used for minimization. See scipy.minimize documentation for all options

cliff.fit.fit_indu_global_parameters(pathname, ref_dict, initial_guess=None, method='bfgs')

Fit induction coefficients

Parameters

• pathname – Path to the dimer xyz files. The comment (second) line in the xyz needs to specify the number of atoms in the first monomer.

• ref_dict – Dictionary containing the reference energies for fitting. The keys to the dictionary need to be the dimer filenames, and the value is a numpy array of energies: [total, elst, exch, indu].

• initial_guess – Numpy array of initial guess parameters (69 total). See the get_energy function for how initial parameters should be ordered. Default is 1.0 for all parameters

• gamma – Gamma parameter between 0 and 1.0 that controls the degree to which the total energy influences fitting.

• method – Algorithm used for minimization. See scipy.minimize documentation for all options

cliff.fit.get_disp_energy(params, pathname, ref)

cliff.fit.get_elst_energy(params, pathname, ref)

cliff.fit.get_energy(params, pathname, gamma, ref)

cliff.fit.get_exch_energy(params, pathname, ref)

cliff.fit.get_indu_energy(params, pathname, ref)

Training functions

train.py Component-based Learned Intermolecular Force Field

Contains functions for training ML models for atomic properties

cliff.train.get_mols(pathname, frac, max_test=None)

cliff.train.run_multipole_krr(ref_file, train_xyzs, ele=None, save=None, hyperparams=None, frac=None, cutoff=None)

cliff.train.train_atomic_properties(reference_properties, train_fraction, save_file)

Trains NN-based model for atomic properties using APNET

Parameters

• reference_properties –

  Location of .pkl file containing reference properties. The pkl file contains a pandas dataframe with the following columns:

  • ’Z’ : The atom types (:class: ~numpy.ndarray of int with shape (n,))

  • ’R’ : Cartesian coordinates (:class: ~numpy.ndarray of float with shape (n,3)

  • ’total_charge’ : The total monomer charge (int)

  • ’cartesian_multipoles’ : Reference atomic charges, dipoles, and quadrupoles (:class: ~numpy.ndarray of float with shape (n,10), in a.u.)

  • ’volume_ratios’ : Reference volume ratios (:class: ~numpy.ndarray of float with shape (n,), no units)

  • ’valence_widths’ : Reference valence widths (:class: ~numpy.ndarray of float with shape (n,))

• train_fraction – Fraction of data set in reference_properties to use for training. Default is 0.9

• save_file – location and filename of ML model. Needs to end in .h5, or else code will enforce.

cliff.train.train_atomic_volume_krr(pathname, ref_file, frac_training, options, element=None, save=None, load=None, max_test=None, cutoff=None)

cliff.train.train_hirshfeld_krr(pathname, ref_file, frac, ele, max_test=None)

cliff.train.train_multipole_krr(pathname, ref_file, frac_training, options, element=None, save=None, load=None, max_test=None, cutoff=None)

Run training/prediction with frac_training ratio