ichor.core.models package

Subpackages

Submodules

ichor.core.models.calculate_fflux_derivatives module

fflux_derivs(iatm_idx, jatm_idx, atoms_instance, system_alf, model_inst)

fflux_derivs_da_df_matrix(jatm_idx, iatm_idx, atoms_instance, system_alf): Calculates columns of the B matrix for one atom (so calculates 3 columns of the B matrix)

Note

assumes the atoms instance is in Bohr.

fflux_derivs_rbf_only(iatm_idx, jatm_idx, atoms_instance, system_alf, model_inst)

fflux_derivs_rbf_only_one_dimensional(iatm_idx, jatm_idx, atoms_instance, system_alf, model_inst)

fflux_predict_value(model_inst, test_x_features)

fflux_predict_value_rbf_only(model_inst, test_x_features)

ichor.core.models.create_datasets module

get_atom_name_and_alf_from_csv(csv_path: Path) → Tuple[str, List[str]]

Helper function to get atom name and alf (as list of str)

Parameters:: csv_path – The csv file path
Returns:: A tuple containing the atom name and alf

write_csvs_intersection(input_dir: str | Path = 'processed_csvs', output_dir: str | Path = 'processed_csvs_intersection')

Not all processed atom csvs might contain the same points. This is because one atom might in a point might be filtered because of integration error but another one might not. This function is used to write out datasets that enforce that all atoms in a point are present in the written out csvs. The function finds the intersection of all point names across the csvs and then only writes out the rows from each csv that are in the intersection.

Parameters:

input_dir – The path to the directory containing processed csvs files, defaults to “processed_csvs”
output_dir – The path to the directory containing output csvs, defaults to “processed_csvs_all_atoms”

write_multiple_train_sets_and_one_test_set(ntrain_initial: int, ntrain_increment: int, nincrements: int, ntest: int, processed_csvs_dir: str | Path = 'processed_csvs', set_path=PosixPath('sets'))

Warning

The function assumes that csvs contain ALL the same points in them.

Note

If there are 0 increments, then it will only make one training set and one test set containing random points (points in the training set are NOT in the test set).

Function used to generate (multiple)training sets and one test set. The training sets contain an increasing number of training points, where bigger training sets contain the smaller training sets in them already. The test set contains points that are outside of the training sets.

Parameters:

ntrain_initial – smallest possible training set size
ntrain_increment – how much to increase the training set size by
nincrements – how many times to increase the training set size
ntest – number of test set points
processed_csvs_dir – Location of processed csvs containing sample set, defaults to “processed_csvs”
set_path – The output directory which will contain the train/test sets, defaults to Path(“sets”)

Raises:

ValueError – if the training+test set size is above the sample set size

write_random_train_test_sets(ntrain: int, ntest: int, processed_csvs_dir: str | Path = 'processed_csvs', set_path=PosixPath('sets'))

Writes out a random training and test set

Parameters:

ntrain – Number of training points
ntest – Number of test points
processed_csvs_dir – Directory with sample set csv files, defaults to “processed_csvs”
set_path – Directory where train/test csvs are going to be written, defaults to Path(“sets”)

ichor.core.models.fflux_derivative_helper_functions module

C_1(iatm_idx, atoms_instance, system_alf)

C_2(iatm_idx, atoms_instance, system_alf)

C_3(iatm_idx, atoms_instance, system_alf)

C_matrix(atoms_instance, iatm_idx, system_alf)

EqC12(iatm_idx, omega, diff, atoms_instance, system_alf)

dC1k_da(iatm_idx, omega, atoms_instance, system_alf)

dC2k_da(iatm_idx, omega, atoms_instance, system_alf)

dC3k_da(c1_vec, c2_vec, dc1k, dc2k)

dChi_da(iatm_idx, omega, atoms_instance, system_alf)

dPhi_da(iatm_idx, jatm_idx, zeta1, zeta2, phi_feat_idx, omega, atoms_instance, system_alf)

dR_da(iatm_idx, jatm_idx, feat_idx, omega, atoms_instance, system_alf)

dRaxdotRax_da(iatm_idx, omega, diff, system_alf)

dRaxdotRaxy_da(iatm_idx, omega, diff1, diff2, system_alf)

dTheta_da(iatm_idx, jatm_idx, theta_feat_idx, zeta3, omega, atoms_instance, system_alf)

dZj_da(iatm_idx, jatm_idx, omega, j, atoms_instance, system_alf)

delta_An(iatm_idx, jatm_idx, omega)

delta_Ax(iatm_idx, omega, system_alf)

delta_Axy(iatm_idx, omega, system_alf)

dsigma_da(iatm_idx, omega, atoms_instance, system_alf)

dyj_da(iatm_idx, omega, diff, atoms_instance, system_alf)

kronecker(i, k)

sigma_fflux(x_axis_diff, xy_plane_diff)

sign_j(fdiff)

y_vec(iatm_idx, atoms_instance, system_alf)

ichor.core.models.gaussian_energy_derivative_wrt_features module

b_matrix_true_finite_differences(atoms, system_alf, central_atom_idx=0, h=1e-06)

Computes the analytical and finite differences B matrix

Parameters:

atoms – An atoms instance containing the geometry for which to calculate the B matrix
central_atom_idx – The atom index for which to calculate a B matrix calculates the df_i / dc_j where f is the features of the central atom
h – The finite difference to add to the Cartesian coordinates before calculating the features, defaults to 1e-6

returns: A tuple of the analytical and finite differences B matrix

convert_to_cartesian_forces(dE_df_array: ndarray, b_matrix: ndarray, system_alf: List[ALF], central_atom_idx: int)

Converts from local ‘feature’ forces to global Cartesian forces, as given by Gaussian.

Parameters:

dE_df_array – 1D array of shape n_features x 1 containing ‘feature’ forces.
b_matrix – Wilson B matrix to be used to calculate, as well as dE/df. Should be of shape (3N-6) x 3N where N is the number of atoms.
system_alf – A list of ALF instances containing the ALF of every atom.
central_atom_idx – The index of the atom (0-indexed) which was the central ALF atom for which features (and feature derivatives) were calculated.

convert_to_feature_forces(global_cartesian_forces: ndarray, b_matrix, system_alf, central_atom_idx)

Compute -dE/df (since the global Cartesian forces are negative of the derivative of the potential). If making models with these values, need to take the NEGATIVE of -dE/df, as the derivative of the potential energy is dE/df.

dE/df are the values that need to be used when adding derivatives to GP model.

Parameters:

global_cartesian_forces – A 2D numpy array of shape (N_atoms, 3) containing the global Cartesian forces. The rows of this array are swapped internally to match the rows of the b-matrix.
b_matrix – Wilson B matrix to be used to calculate, as well as dE/df. Should be of shape (3N-6) x 3N where N is the number of atoms.
system_alf – A list of ALF instances containing the ALF of every atom.
central_atom_idx – The index of the atom (0-indexed) which was the central ALF atom for which features (and feature derivatives) were calculated.

Note

The ordering of the forces should match up with the ordering of the b_matrix.

See Using Redundant Internal Coordinates to Optimize Equilibrium Geometries and Transition States https://doi.org/10.1002/(SICI)1096-987X(19960115)17:1<49::AID-JCC5>3.0.CO;2-0 https://doi.org/10.1063/1.462844

form_b_matrix(atoms: Atoms, system_alf: List[ALF], central_atom_idx) → ndarray

Returns a np array of shape n_features x n_atomsx3, containing the derivative of features with respect to x,y,z coordiantes.

\[B_{ij} = \frac{df_i}{dx_j}\]

where the partial derivative of feature i \(f_i\) wrt. partial derivative of global Cartesian \(x_j\).

See the following papers for details:

Using redundant internal coordinates to optimize equilibrium geometries and transition states:

link1

Geometry optimization in redundant internal coordinates:

link2

The first three columns of the B-matrix are for atom \(A_0\).

\(\frac{df_i}{dA^0_x}, \frac{df_i}{dA^0_y}, \frac{df_i}{dA^0_z}\)

The next three columns of the B-matrix are for atom \(A_x\).

\(\frac{df_i}{dA^x_x}, \frac{df_i}{dA^x_y}, \frac{df_i}{dA^x_z}\)

The next three columns of the B-matrix are for atom \(A^{xy}\).

\(\frac{df_i}{dA^{xy}_x}, \frac{df_i}{dA^{xy}_y}, \frac{df_i}{dA^{xy}_z}\)

The subsequent sets of three columns of the B-matrix are for atom \(A^n\). which are atoms described by r, theta, phi.

\(\frac{df_i}{dA^n_x}, \frac{df_i}{dA^n_y}, \frac{df_i}{dA^n_z}\)

Note

The atoms instance is converted to Bohr internally because the forces are per Bohr in FFLUX. Also the system_alf argument is 0-indexed (as calculated by ichor methods), while the ALF in the .model files is 1-indexed.

Parameters:

atoms – The Atoms instance for which to calculate the Wilson B matrix. The B matrix is calculated from the coordinates of the atoms.
system_alf – The system alf as a list of ALF instances (the ALF instances are just a named tuple containing origin_idx, x-axis_idx, xy_plane_idx. It is 0-indexed.)
index (central atom) – The index of the atom to be used as the central atom. Therefore, the derivatives df_i / dx_j are going to be for the features of this atom.

form_g_inverse(g_matrix: ndarray): Inverts the G matrix, gives generalized inverse

form_g_matrix(b_matrix: ndarray): Forms the G matrix as in Gaussian.

Note

G is a symmetric square (BuB^T, where u is the identity matrix here))

ichor.core.models.model module

class Model(path: Path, system_name: str = FileContents, atom_name: str = FileContents, prop: str = FileContents, alf: ALF = FileContents, natoms: int = FileContents, ntrain: int = FileContents, nfeats: int = FileContents, mean: Mean = FileContents, kernel: Kernel = FileContents, x: ndarray = FileContents, y: ndarray = FileContents, input_units: List[str] = FileContents, output_unit: str = FileContents, likelihood: float = FileContents, jitter: float = FileContents, weights: ndarray = FileContents, program: str = FileContents, program_version: Version = FileContents, notes: Dict[str, str] = FileContents)

Bases: ReadFile, WriteFile

A model file that is returned back from our machine learning program FEREBUS.

Note

Another program can be used for the machine learning as long as it outputs files of the same format as the FEREBUS outputs.

property R: ndarray: Returns the covariance matrix and adds a jitter to the diagonal for numerical stability. This jitter is a very small number on the order of 1e-6 to 1e-10.

property atom: str: alias for atom_name

property atom_num: int: Returns the integer that is in the atom name

compute_likelihood() → float: Computes the marginal likelihood from the data given

compute_weights() → ndarray: Computes the training weights from the data given

property i: int: Returns the integer that is one less than the one in the atom name. This is the index of the atom in Python objects such as lists (as indeces start at 0).

property ialf: ndarray

Returns the atomic local frame, indices start at 0 (as in Python).

Returns:: The 0-indexed np.ndarray corresponding to the alf of the atom.

property invR: ndarray: Returns the inverse of the covariance matrix R

property logdet

property lower_cholesky: ndarray: Decomposes the covariance matrix into L and L^T. Returns the lower triangular matrix L.

path: Path | str

predict(x_test: ndarray) → ndarray: Returns an array containing the test point predictions.

r(x_test: ndarray) → ndarray: Returns the n_train by n_test covariance matrix

property type: str: alias for prop

variance(x_test: ndarray) → ndarray: Return the variance for the test data points.

ichor.core.models.model_with_gradient module

class ModelWithGradients(path: Path)

Bases: ReadFile

property R: ndarray: Returns the covariance matrix and adds a jitter to the diagonal for numerical stability. This jitter is a very small number on the order of 1e-6 to 1e-10.

property atom: str: alias for atom_name

property atom_num: int: Returns the integer that is in the atom name

property i: int: Returns the integer that is one less than the one in the atom name. This is the index of the atom in Python objects such as lists (as indeces start at 0).

property ialf: ndarray

Returns the atomic local frame, indices start at 0 (as in Python).

Returns:: The 0-indexed np.ndarray corresponding to the alf of the atom.

property invR: ndarray: Returns the inverse of the covariance matrix R

property logdet

property lower_cholesky: ndarray: Decomposes the covariance matrix into L and L^T. Returns the lower triangular matrix L.

path: Path | str

predict(x_test: ndarray) → ndarray: Returns an array containing the test point predictions.

r(x_test: ndarray) → ndarray: Returns the n_train by n_test covariance matrix

property type: str: alias for prop

variance(x_test: ndarray) → ndarray: Return the variance for the test data points.

ichor.core.models.models module

exception DimensionError: Bases: ValueError

class Models(path)

Bases: Directory, list

A class which wraps around a directory containing models made by FEREBUS or any other program used to make GP models. There are different models for iqa energy and each individual multipole moment. Aditionally, every atom in the system has its own set of models for iqa and multipole moments. These models can have different training input/output data if the models have been made with per-atom.

property alf: List[ALF]: Returns the alf taken straight from each model file e.g. [[1, 2, 3], [2, 1, 3], [3, 1, 2]]

property atom_names: List[str]: Returns a list of atom names (such as O1, H2, H3, etc.) for which models were made

classmethod check_path(path: Path) → bool: Implement if the path of the directory needs to be checked if it contains something specific

dirpattern(pattern): A regex pattern used to find directories containing models.

get_features_dict(test_x: Atoms | ListOfAtoms | ndarray | HasAtoms | dict) → Dict[str, ndarray]

Returns a dictionary containing the atom names as keys and an np.ndarray of features as values.

Parameters:: test_x – An object that contains features (or coordinates that can be converted into features), such as Atoms, ListOfAtoms, np.ndarray, dict
Returns:: A dictionary containing the atom names as keys and an np.ndarray of features as values

property ialf: ndarray: Returns the zero index alf from each model file as a numpy array e.g. [[0, 1, 2], [1, 0, 2], [2, 0, 1]]

Note

Sorting by the first integer in elements of the list will give a list like this [[0,…], [1,….], [2,….]]. Before that the list could look like [[2,…], [0,….], [1,….]] (because the models could be unordered) which would mess up the alf for atoms.

property ialf_dict: Dict[str, ndarray]: Returns the zero index alf from each model file as a dictionary e.g. {‘O1’: [0, 1, 2], ‘H2’: [1, 0, 2], ‘H3’: [2, 0, 1]}

property ntrain: int: Returns the maximum number of training points that were used for a model in this Models instance.

path: Path | str

predict(x_test) → DataFrame: Returns dictionary of DataFrame({“atom”: {“property”: [values]}})

property system: str: Returns the name of the system for which models were made.

property types: List[str]: Returns a list of types (such as q00, q10, iqa, etc.) for which models were made

variance(x_test) → DataFrame

class ModelsView(models, *args)

Bases: Models

path: Path | str

x_to_features(func: F) → F: Used as a decorator to convert an incoming set of test points x to features because we need to know the test point features in order to make predictions.

ichor.core.models.predict_forces_for_all_atoms module

predict_fflux_forces_for_all_atoms(atoms: Atoms, models: ichor.core.models.Models, system_alf: List[ALF]) → ndarray

Predicts the forces that FFLUX predicts (which are written to IQA_FORCES file).

Note

The atoms instance is converted to Bohr internally because the forces are per Bohr in FFLUX. Also the system_alf argument is 0-indexed (as calcualted by ichor methods), while the ALF in the .model files is 1-indexed.

Parameters:

atoms – An Atoms instance containing the geometry for which to predict forces. Note that the ordering of the atoms matters, i.e. the index of the atoms in the Atoms instance must match the index of the model files.
models – A models instance which wraps around a directory containing model files.
system_alf – The system alf as a list of ALF instances (the ALF instances are just a named tuple containing origin_idx, x-axis_idx, xy_plane_idx. It is 0-indexed.)

Returns:

A np.ndarray of shape n_atoms x 3 containing the x,y,z force for every atom

predict_fflux_forces_for_all_atoms_dict(atoms: Atoms, models: ichor.core.models.Models, system_alf: List[ALF]) → Dict[str, ndarray]

Predicts the forces that FFLUX predicts (which are written to IQA_FORCES file).

Note

The atoms instance is converted to Bohr internally because the forces are per Bohr in FFLUX. Also the system_alf argument is 0-indexed (as calcualted by ichor methods), while the ALF in the .model files is 1-indexed.

Parameters:

atoms – An Atoms instance containing the geometry for which to predict forces. Note that the ordering of the atoms matters, i.e. the index of the atoms in the Atoms instance must match the index of the model files.
models – A models instance which wraps around a directory containing model files.
system_alf – The system alf as a list of ALF instances (the ALF instances are just a named tuple containing origin_idx, x-axis_idx, xy_plane_idx. It is 0-indexed.)

Returns:

A dictionary of key: atom_name, value: 1D np.ndarray containing the x,y,z forces on the atom.

predict_fflux_forces_for_all_atoms_one_dimensional(atoms: Atoms, models: ichor.core.models.Models, system_alf: List[ALF]) → ndarray

Predicts the forces that FFLUX predicts (which are written to IQA_FORCES file). Note this is for special case where the system has only one feature, eg. HCl.

Note

The atoms instance is converted to Bohr internally because the forces are per Bohr in FFLUX. Also the system_alf argument is 0-indexed (as calcualted by ichor methods), while the ALF in the .model files is 1-indexed.

Parameters:

atoms – An Atoms instance containing the geometry for which to predict forces. Note that the ordering of the atoms matters, i.e. the index of the atoms in the Atoms instance must match the index of the model files.
models – A models instance which wraps around a directory containing model files.
system_alf – The system alf as a list of ALF instances (the ALF instances are just a named tuple containing origin_idx, x-axis_idx, xy_plane_idx. It is 0-indexed.)

Returns:

A np.ndarray of shape n_atoms x 3 containing the x,y,z force for every atom

Module contents

class Model(path: Path, system_name: str = FileContents, atom_name: str = FileContents, prop: str = FileContents, alf: ALF = FileContents, natoms: int = FileContents, ntrain: int = FileContents, nfeats: int = FileContents, mean: Mean = FileContents, kernel: Kernel = FileContents, x: ndarray = FileContents, y: ndarray = FileContents, input_units: List[str] = FileContents, output_unit: str = FileContents, likelihood: float = FileContents, jitter: float = FileContents, weights: ndarray = FileContents, program: str = FileContents, program_version: Version = FileContents, notes: Dict[str, str] = FileContents)

Bases: ReadFile, WriteFile

A model file that is returned back from our machine learning program FEREBUS.

Note

Another program can be used for the machine learning as long as it outputs files of the same format as the FEREBUS outputs.

property R: ndarray: Returns the covariance matrix and adds a jitter to the diagonal for numerical stability. This jitter is a very small number on the order of 1e-6 to 1e-10.

property atom: str: alias for atom_name

property atom_num: int: Returns the integer that is in the atom name

compute_likelihood() → float: Computes the marginal likelihood from the data given

compute_weights() → ndarray: Computes the training weights from the data given

property i: int: Returns the integer that is one less than the one in the atom name. This is the index of the atom in Python objects such as lists (as indeces start at 0).

property ialf: ndarray

Returns the atomic local frame, indices start at 0 (as in Python).

Returns:: The 0-indexed np.ndarray corresponding to the alf of the atom.

property invR: ndarray: Returns the inverse of the covariance matrix R

property logdet

property lower_cholesky: ndarray: Decomposes the covariance matrix into L and L^T. Returns the lower triangular matrix L.

path: Path | str

predict(x_test: ndarray) → ndarray: Returns an array containing the test point predictions.

r(x_test: ndarray) → ndarray: Returns the n_train by n_test covariance matrix

property type: str: alias for prop

variance(x_test: ndarray) → ndarray: Return the variance for the test data points.

class ModelWithGradients(path: Path)

Bases: ReadFile

property R: ndarray: Returns the covariance matrix and adds a jitter to the diagonal for numerical stability. This jitter is a very small number on the order of 1e-6 to 1e-10.

alf: ALF

property atom: str: alias for atom_name

atom_name: str

property atom_num: int: Returns the integer that is in the atom name

property i: int: Returns the integer that is one less than the one in the atom name. This is the index of the atom in Python objects such as lists (as indeces start at 0).

property ialf: ndarray

Returns the atomic local frame, indices start at 0 (as in Python).

Returns:: The 0-indexed np.ndarray corresponding to the alf of the atom.

input_units: List[str]

property invR: ndarray: Returns the inverse of the covariance matrix R

kernel: Kernel

property logdet

property lower_cholesky: ndarray: Decomposes the covariance matrix into L and L^T. Returns the lower triangular matrix L.

mean: float

natoms: int

nfeats: int

notes: Dict[str, str]

ntrain: int

output_unit: str

path: Path | str

predict(x_test: ndarray) → ndarray: Returns an array containing the test point predictions.

program: str

program_version: str

prop: str

r(x_test: ndarray) → ndarray: Returns the n_train by n_test covariance matrix

system_name: str

task_noises: ndarray

property type: str: alias for prop

variance(x_test: ndarray) → ndarray: Return the variance for the test data points.

x: ndarray

y: ndarray

class Models(path)

Bases: Directory, list

A class which wraps around a directory containing models made by FEREBUS or any other program used to make GP models. There are different models for iqa energy and each individual multipole moment. Aditionally, every atom in the system has its own set of models for iqa and multipole moments. These models can have different training input/output data if the models have been made with per-atom.

property alf: List[ALF]: Returns the alf taken straight from each model file e.g. [[1, 2, 3], [2, 1, 3], [3, 1, 2]]

property atom_names: List[str]: Returns a list of atom names (such as O1, H2, H3, etc.) for which models were made

classmethod check_path(path: Path) → bool: Implement if the path of the directory needs to be checked if it contains something specific

dirpattern(pattern): A regex pattern used to find directories containing models.

get_features_dict(test_x: Atoms | ListOfAtoms | ndarray | HasAtoms | dict) → Dict[str, ndarray]

Returns a dictionary containing the atom names as keys and an np.ndarray of features as values.

Parameters:: test_x – An object that contains features (or coordinates that can be converted into features), such as Atoms, ListOfAtoms, np.ndarray, dict
Returns:: A dictionary containing the atom names as keys and an np.ndarray of features as values

property ialf: ndarray: Returns the zero index alf from each model file as a numpy array e.g. [[0, 1, 2], [1, 0, 2], [2, 0, 1]]

Note

Sorting by the first integer in elements of the list will give a list like this [[0,…], [1,….], [2,….]]. Before that the list could look like [[2,…], [0,….], [1,….]] (because the models could be unordered) which would mess up the alf for atoms.

property ialf_dict: Dict[str, ndarray]: Returns the zero index alf from each model file as a dictionary e.g. {‘O1’: [0, 1, 2], ‘H2’: [1, 0, 2], ‘H3’: [2, 0, 1]}

property ntrain: int: Returns the maximum number of training points that were used for a model in this Models instance.

path: Path | str

predict(x_test) → DataFrame: Returns dictionary of DataFrame({“atom”: {“property”: [values]}})

property system: str: Returns the name of the system for which models were made.

property types: List[str]: Returns a list of types (such as q00, q10, iqa, etc.) for which models were made

variance(x_test) → DataFrame