DeepChem has a broad collection of utility functions. Many of these
maybe be of independent interest to users since they deal with some
tricky aspects of processing scientific datatypes.
clean_mols (bool, default True) – Whether to sanitize molecules.
tasks (List[str], default []) – Each entry in tasks is treated as a property in the SDF file and is
retrieved with mol.GetProp(str(task)) where mol is the RDKit mol
loaded from a given SDF entry.
shard_size (int, default None) – The shard size to yield at one time.
Returns:
Generator which yields the dataframe which is the same shard size.
shard_size (int, default None) – Chunksize for reading json files.
Returns:
Generator which yields the dataframe which is the same shard size.
Return type:
Iterator[pd.DataFrame]
Notes
To load shards from a json file into a Pandas dataframe, the file
must be originally saved with df.to_json('filename.json',orient='records',lines=True)
Utility used by MoleculeNet to save train/valid/test datasets.
This utility function saves a train/valid/test split of a dataset along
with transformers in the same directory. The saved datasets will take the
following structure:
save_dir/
max_conformers (int, optional (default 1)) – Maximum number of conformers to generate (after pruning).
rmsd_threshold (float, optional (default 0.5)) – RMSD threshold for pruning conformers. If None or negative, no
pruning is performed.
force_field (str, optional (default 'uff')) – Force field to use for conformer energy calculation and
minimization. Options are ‘uff’, ‘mmff94’, and ‘mmff94s’.
pool_multiplier (int, optional (default 10)) – Factor to multiply by max_conformers to generate the initial
conformer pool. Since conformers are pruned after energy
minimization, increasing the size of the pool increases the chance
of identifying max_conformers unique conformers.
Converts molecule file to (xyz-coords, obmol object)
Given molecule_file, returns a tuple of xyz coords of molecule
and an rdkit object representing that molecule in that order (xyz,
rdkit_mol). This ordering convention is used in the code in a few
places.
Parameters:
molecule_file (str) – filename for molecule
add_hydrogens (bool, optional (default True)) – If True, add hydrogens via pdbfixer
calc_charges (bool, optional (default True)) – If True, add charges via rdkit
sanitize (bool, optional (default False)) – If True, sanitize molecules via rdkit
is_protein (bool, optional (default False)) – If True`, this molecule is loaded as a protein. This flag will
affect some of the cleanup procedures applied.
Returns:
Tuple (xyz, mol) if file contains single molecule. Else returns a
list of the tuples for the separate molecules in this list.
It’s often convenient to represent a fragment of a molecule. For
example, if two molecules form a molecular complex, it may be useful
to create two fragments which represent the subsets of each molecule
that’s close to the other molecule (in the contact region).
Ideally, we’d be able to do this in RDKit direct, but manipulating
molecular fragments doesn’t seem to be supported functionality.
We use this class instead of raw RDKit atoms since manipulating a
large number of rdkit Atoms seems to result in segfaults. Wrapping
the basic information in an AtomShim seems to avoid issues.
Molecular complexes can get very large. This can make it unwieldy to
compute functions on them. To improve memory usage, it can be very
useful to trim out atoms that aren’t close to contact regions. This
function computes pairwise distances between all pairs of molecules
in the molecular complex. If an atom is within cutoff distance of
any atom on another molecule in the complex, it is regarded as a
contact atom. Otherwise it is trimmed.
Parameters:
fragments (List[Tuple[np.ndarray, rdkit.Chem.rdchem.Mol]]) – As returned by rdkit_utils.load_complex, a list of tuples of
(coords, mol) where coords is a (N_atoms, 3) array and mol
is the rdkit molecule object.
cutoff (float, optional (default 4.5)) – The cutoff distance in angstroms.
Returns:
A list of length len(molecular_complex). Each entry in this list
is a list of atom indices from that molecule which should be kept, in
sorted order.
Reduce a molecular complex to only those atoms near a contact.
Molecular complexes can get very large. This can make it unwieldy to
compute functions on them. To improve memory usage, it can be very
useful to trim out atoms that aren’t close to contact regions. This
function takes in a molecular complex and returns a new molecular
complex representation that contains only contact atoms. The contact
atoms are computed by calling get_contact_atom_indices under the
hood.
Parameters:
fragments (List[Tuple[np.ndarray, rdkit.Chem.rdchem.Mol]]) – As returned by rdkit_utils.load_complex, a list of tuples of
(coords, mol) where coords is a (N_atoms, 3) array and mol
is the rdkit molecule object.
cutoff (float) – The cutoff distance in angstroms.
Returns:
A list of length len(molecular_complex). Each entry in this list
is a tuple of (coords, MolecularFragment). The coords is stripped
down to (N_contact_atoms, 3) where N_contact_atoms is the number
of contact atoms for this complex. MolecularFragment is used since
it’s tricky to make a RDKit sub-molecule.
A coordinate box that represents a block in space.
Molecular complexes are typically represented with atoms as
coordinate points. Each complex is naturally associated with a
number of different box regions. For example, the bounding box is a
box that contains all atoms in the molecular complex. A binding
pocket box is a box that focuses in on a binding region of a protein
to a ligand. A interface box is the region in which two proteins
have a bulk interaction.
The CoordinateBox class is designed to represent such regions of
space. It consists of the coordinates of the box, and the collection
of atoms that live in this box alongside their coordinates.
interval1 (Tuple[float, float]) – Should be (x1_min, x1_max)
interval2 (Tuple[float, float]) – Should be (x2_min, x2_max)
Returns:
x_intersect – Should be the intersection. If the intersection is empty returns
(0, 0) to represent the empty set. Otherwise is (max(x1_min,
x2_min), min(x1_max, x2_max)).
For each face of the convex hull, compute a coordinate box around it.
The convex hull of a macromolecule will have a series of triangular
faces. For each such triangular face, we construct a bounding box
around this triangle. Think of this box as attempting to capture
some binding interaction region whose exterior is controlled by the
box. Note that this box will likely be a crude approximation, but
the advantage of this technique is that it only uses simple geometry
to provide some basic biological insight into the molecule at hand.
The pad parameter is used to control the amount of padding around
the face to be used for the coordinate box.
Parameters:
coords (np.ndarray) – A numpy array of shape (N, 3). The coordinates of a molecule.
pad (float, optional (default 5.0)) – The number of angstroms to pad.
The evaluator class is used to evaluate a dc.models.Model class on
a given dc.data.Dataset object. The evaluator is aware of
dc.trans.Transformer objects so will automatically undo any
transformations which have been applied.
Examples
Evaluators allow for a model to be evaluated directly on a Metric
for sklearn. Let’s do a bit of setup constructing our dataset and
model.
Then you can evaluate this model as follows
>>> import sklearn
>>> evaluator = Evaluator(model, dataset, transformers)
>>> multitask_scores = evaluator.compute_model_performance(
… sklearn.metrics.mean_absolute_error)
Evaluators can also be used with dc.metrics.Metric objects as well
in case you want to customize your metric further.
model (Model) – Model to evaluate. Note that this must be a regression or
classification model and not a generative model.
dataset (Dataset) – Dataset object to evaluate model on.
transformers (List[Transformer]) – List of dc.trans.Transformer objects. These transformations
must have been applied to dataset previously. The dataset will
be untransformed for metric evaluation.
Computes statistics of model on test data and saves results to csv.
Parameters:
metrics (dc.metrics.Metric/list[dc.metrics.Metric]/function) – The set of metrics provided. This class attempts to do some
intelligent handling of input. If a single dc.metrics.Metric
object is provided or a list is provided, it will evaluate
self.model on these metrics. If a function is provided, it is
assumed to be a metric function that this method will attempt to
wrap in a dc.metrics.Metric object. A metric function must
accept two arguments, y_true, y_pred both of which are
np.ndarray objects and return a floating point score. The
metric function may also accept a keyword argument
sample_weight to account for per-sample weights.
csv_out (str, optional (DEPRECATED)) – Filename to write CSV of model predictions.
stats_out (str, optional (DEPRECATED)) – Filename to write computed statistics.
per_task_metrics (bool, optional) – If true, return computed metric for each task on multitask dataset.
use_sample_weights (bool, optional (default False)) – If set, use per-sample weights w.
n_classes (int, optional (default None)) – If specified, will use n_classes as the number of unique classes
in self.dataset. Note that this argument will be ignored for
regression metrics.
Returns:
multitask_scores (dict) – Dictionary mapping names of metrics to metric scores.
all_task_scores (dict, optional) – If per_task_metrics == True, then returns a second dictionary
of scores for each task separately.
This class is a partner class to Evaluator. Instead of operating
over datasets this class operates over a generator which yields
batches of data to feed into provided model.
Evaluators can also be used with dc.metrics.Metric objects as well
in case you want to customize your metric further. (Note that a given
generator can only be used once so we have to redefine the generator here.)
generator (generator) – Generator which yields batches to feed into the model. For a
KerasModel, it should be a tuple of the form (inputs, labels,
weights). The “correct” way to create this generator is to use
model.default_generator as shown in the example above.
transformers (List[Transformer]) – Tranformers to “undo” when applied to the models outputs
labels (list of Layer) – layers which are keys in the generator to compare to outputs
weights (list of Layer) – layers which are keys in the generator for weight matrices
Computes statistics of model on test data and saves results to csv.
Parameters:
metrics (dc.metrics.Metric/list[dc.metrics.Metric]/function) – The set of metrics provided. This class attempts to do some
intelligent handling of input. If a single dc.metrics.Metric
object is provided or a list is provided, it will evaluate
self.model on these metrics. If a function is provided, it is
assumed to be a metric function that this method will attempt to
wrap in a dc.metrics.Metric object. A metric function must
accept two arguments, y_true, y_pred both of which are
np.ndarray objects and return a floating point score.
per_task_metrics (bool, optional) – If true, return computed metric for each task on multitask
dataset.
use_sample_weights (bool, optional (default False)) – If set, use per-sample weights w.
n_classes (int, optional (default None)) – If specified, will assume that all metrics are classification
metrics and will use n_classes as the number of unique classes
in self.dataset.
Returns:
multitask_scores (dict) – Dictionary mapping names of metrics to metric scores.
all_task_scores (dict, optional) – If per_task_metrics == True, then returns a second dictionary
of scores for each task separately.
Run hhblits multisequence alignment search on a dataset. This function
requires the hhblits binary to be installed and in the path. This function
also requires a Hidden Markov Model reference database to be provided. Both can be
found here: https://github.com/soedinglab/hh-suite
The database should be in the deepchem data directory or specified as an argument.
To set the deepchem data directory, run this command in your environment:
export DEEPCHEM_DATA_DIR=<path to data directory>
Parameters:
dataset_path (str) – Path to single sequence or multiple sequence alignment (MSA) dataset. Results will be saved in this directory.
database (str) – Name of database to search against. Note this is not the path, but the name of the database.
data_dir (str) – Path to database directory.
evalue (float) – E-value cutoff.
num_iterations (int) – Number of iterations.
num_threads (int) – Number of threads.
Returns:
results (.a3m file) – MSA file containing the results of the hhblits search.
results (.hhr file) – hhsuite results file containing the results of the hhblits search.
Run hhsearch multisequence alignment search on a dataset. This function
requires the hhblits binary to be installed and in the path. This function
also requires a Hidden Markov Model reference database to be provided. Both can be
found here: https://github.com/soedinglab/hh-suite
The database should be in the deepchem data directory or specified as an argument.
To set the deepchem data directory, run this command in your environment:
Generate a random unit vector u, randomly sampled from the
unit sphere (see function generate_random_unit_vector()
for details)
Generate a second random unit vector v
If absolute value of u dot v > 0.99, repeat.
(This is important for numerical stability. Intuition: we
want them to be as linearly independent as possible or
else the orthogonalized version of v will be much shorter
in magnitude compared to u. I assume in Stack they took
this from Gram-Schmidt orthogonalization?)
v” = v - (u dot v)*u, i.e. subtract out the component of
v that’s in u’s direction
normalize v” (this isn”t in Stack but I assume it must be
done)
find w = u cross v”
u, v”, and w will form the columns of a rotation matrix, R.
The intuition is that u, v” and w are, respectively, what
the standard basis vectors e1, e2, and e3 will be mapped
to under the transformation.
Returns:
R – A numpy array of shape (3, 3). R is a rotation matrix.
Fourier encode the input tensor x based on the specified number of encodings.
This function applies a Fourier encoding to the input tensor x by dividing
it by a range of scales (2^i for i in range(num_encodings)) and then
concatenating the sine and cosine of the scaled values. Optionally, the
original input tensor can be included in the output.
Parameters:
x (torch.Tensor) – Input tensor to be Fourier encoded.
num_encodings (int, optional, default=4) – Number of Fourier encodings to apply.
include_self (bool, optional, default=True) – Whether to include the original input tensor in the output.
Returns an int < size representing that ECFP pair.
Input must be a tuple of strings. This utility is primarily used for
spatial contact featurizers. For example, if a protein and ligand
have close contact region, the first string could be the protein’s
fragment and the second the ligand’s fragment. The pair could be
hashed together to achieve one hash value for this contact region.
Parameters:
ecfp_pair (Tuple[str, str]) – Pair of ECFP fragment strings
size (int, optional (default 1024)) – Hash to an int in range [0, size)
Returns:
ecfp_hash – An int < size representing given ECFP pair.
Helper function to vectorize a spatial description from a hash.
Hash functions are used to perform spatial featurizations in
DeepChem. However, it’s necessary to convert backwards from
the hash function to feature vectors. This function aids in
this conversion procedure. It creates a vector of zeros of length
size. It then loops through feature_dict, uses hash_function
to hash the stored value to an integer in range [0, size) and bumps
that index.
Parameters:
hash_function (Function, Callable[[str, int], int]) – Should accept two arguments, feature, and size and
return a hashed integer. Here feature is the item to
hash, and size is an int. For example, if size=1024,
then hashed values must fall in range [0, 1024).
feature_dict (Dict, optional (default None)) – Maps unique keys to features computed.
size (int (default 1024)) – Length of generated bit vector
feature_list (List, optional (default None)) – List of features.
This function offsets molecular atom coordinates by
(box_width/2, box_width/2, box_width/2) and then divides by
voxel_width to compute the voxel indices.
Parameters:
coordinates (np.ndarray) – Array with coordinates of all atoms in the molecule, shape (N, 3).
atom_index (int) – Index of an atom in the molecule.
box_width (float) – Size of the box in Angstroms.
voxel_width (float) – Size of a voxel in Angstroms
Returns:
indices – A 1D numpy array of length 3 with [i, j, k], the voxel coordinates
of specified atom.
This helper function helps convert a hash function which
specifies spatial features of a molecular complex into a voxel
tensor. This utility is used by various featurizers that generate
voxel grids.
Parameters:
get_voxels (Function) – Function that voxelizes inputs
coordinates (Any) – Contains the 3D coordinates of a molecular system. This should have
whatever type get_voxels() expects as its first argument.
box_width (float, optional (default 16.0)) – Size of a box in which voxel features are calculated. Box
is centered on a ligand centroid.
voxel_width (float, optional (default 1.0)) – Size of a 3D voxel in a grid in Angstroms.
hash_function (Function) – Used to map feature choices to voxel channels.
feature_dict (Dict, optional (default None)) – Keys are atom indices or tuples of atom indices, the values are
computed features. If hash_function is not None, then the values
are hashed using the hash function into [0, nb_channels) and
this channel at the voxel for the given key is incremented by 1
for each dictionary entry. If hash_function is None, then the
value must be a vector of size (n_channels,) which is added to
the existing channel values at that voxel grid.
feature_list (List, optional (default None)) – List of atom indices or tuples of atom indices. This can only be
used if nb_channel==1. Increments the voxels corresponding to
these indices by 1 for each entry.
nb_channel (int, , optional (default 16)) – The number of feature channels computed per voxel. Should
be a power of 2.
dtype (str ('int' or 'float'), optional (default 'int')) – The type of the numpy ndarray created to hold features.
Returns:
feature_tensor – The voxel of the input with the shape
(voxels_per_edge, voxels_per_edge, voxels_per_edge, nb_channel).
val (int or str) – The value must be present in allowable_set.
allowable_set (List[int] or List[str]) – List of allowable quantities.
include_unknown_set (bool, default False) – If true, the index of all values not in allowable_set is len(allowable_set).
Returns:
An one-hot vector of val.
If include_unknown_set is False, the length is len(allowable_set).
If include_unknown_set is True, the length is len(allowable_set) + 1.
Return type:
List[float]
Raises:
ValueError – If include_unknown_set is False and val is not in allowable_set.
allowable_set (List[str]) – The atom types to consider. The default set is
[“C”, “N”, “O”, “F”, “P”, “S”, “Cl”, “Br”, “I”].
include_unknown_set (bool, default True) – If true, the index of all atom not in allowable_set is len(allowable_set).
Returns:
An one-hot vector of atom types.
If include_unknown_set is False, the length is len(allowable_set).
If include_unknown_set is True, the length is len(allowable_set) + 1.
Get an one-hot feat about whether an atom accepts electrons or donates electrons.
Parameters:
atom (rdkit.Chem.rdchem.Atom) – RDKit atom object
hydrogen_bonding (List[Tuple[int, str]]) – The return value of construct_hydrogen_bonding_info.
The value is a list of tuple (atom_index, hydrogen_bonding) like (1, “Acceptor”).
Returns:
A one-hot vector of the ring size type. The first element
indicates “Donor”, and the second element indicates “Acceptor”.
allowable_set (List[str]) – The hybridization types to consider. The default set is [“SP”, “SP2”, “SP3”]
include_unknown_set (bool, default False) – If true, the index of all types not in allowable_set is len(allowable_set).
Returns:
An one-hot vector of the hybridization type.
If include_unknown_set is False, the length is len(allowable_set).
If include_unknown_set is True, the length is len(allowable_set) + 1.
Get an one-hot feature of the number of hydrogens which an atom has.
Parameters:
atom (rdkit.Chem.rdchem.Atom) – RDKit atom object
allowable_set (List[int]) – The number of hydrogens to consider. The default set is [0, 1, …, 4]
include_unknown_set (bool, default True) – If true, the index of all types not in allowable_set is len(allowable_set).
Returns:
A one-hot vector of the number of hydrogens which an atom has.
If include_unknown_set is False, the length is len(allowable_set).
If include_unknown_set is True, the length is len(allowable_set) + 1.
Get an one-hot feature of the degree which an atom has.
Parameters:
atom (rdkit.Chem.rdchem.Atom) – RDKit atom object
allowable_set (List[int]) – The degree to consider. The default set is [0, 1, …, 5]
include_unknown_set (bool, default True) – If true, the index of all types not in allowable_set is len(allowable_set).
Returns:
A one-hot vector of the degree which an atom has.
If include_unknown_set is False, the length is len(allowable_set).
If include_unknown_set is True, the length is len(allowable_set) + 1.
allowable_set (List[str]) – The bond types to consider. The default set is [“SINGLE”, “DOUBLE”, “TRIPLE”, “AROMATIC”].
include_unknown_set (bool, default False) – If true, the index of all types not in allowable_set is len(allowable_set).
Returns:
A one-hot vector of the bond type.
If include_unknown_set is False, the length is len(allowable_set).
If include_unknown_set is True, the length is len(allowable_set) + 1.
Get an one-hot feature of the stereo configuration of a bond.
Parameters:
bond (rdkit.Chem.rdchem.Bond) – RDKit bond object
allowable_set (List[str]) – The stereo configuration types to consider.
The default set is [“STEREONONE”, “STEREOANY”, “STEREOZ”, “STEREOE”].
include_unknown_set (bool, default True) – If true, the index of all types not in allowable_set is len(allowable_set).
Returns:
A one-hot vector of the stereo configuration of a bond.
If include_unknown_set is False, the length is len(allowable_set).
If include_unknown_set is True, the length is len(allowable_set) + 1.
graph_dist_matrix (np.ndarray) – The return value of Chem.GetDistanceMatrix(mol). The shape is (num_atoms, num_atoms).
allowable_set (List[int]) – The graph distance types to consider. The default set is [1, 2, …, 7].
include_unknown_set (bool, default False) – If true, the index of all types not in allowable_set is len(allowable_set).
Returns:
A one-hot vector of the graph distance.
If include_unknown_set is False, the length is len(allowable_set).
If include_unknown_set is True, the length is len(allowable_set) + 1.
Utility to extract grover attributes for grover model
Parameters:
molgraph (BatchGraphData) – A batched graph data representing a collection of molecules.
Returns:
graph_attributes – A tuple containing atom features, bond features, atom to bond mapping, bond to atom mapping, bond to reverse bond mapping, atom to atom mapping, atom scope, bond scope, functional group labels and other additional features.
Autodock Vina accepts a configuration file which provides options
under which Vina is invoked. This utility function writes a vina
configuration file which directs Autodock vina to perform docking
under the provided options.
Parameters:
protein_filename (str) – Filename for protein
ligand_filename (str) – Filename for the ligand
centroid (np.ndarray) – A numpy array with shape (3,) holding centroid of system
box_dims (np.ndarray) – A numpy array of shape (3,) holding the size of the box to dock
conf_filename (str) – Filename to write Autodock Vina configuration to.
num_modes (int, optional (default 9)) – The number of binding modes Autodock Vina should find
exhaustiveness (int, optional) – The exhaustiveness of the search to be performed by Vina
GNINA accepts a configuration file which provides options
under which GNINA is invoked. This utility function writes a
configuration file which directs GNINA to perform docking
under the provided options.
Parameters:
protein_filename (str) – Filename for protein
ligand_filename (str) – Filename for the ligand
conf_filename (str) – Filename to write Autodock Vina configuration to.
num_modes (int, optional (default 9)) – The number of binding modes GNINA should find
exhaustiveness (int, optional) – The exhaustiveness of the search to be performed by GNINA
This function loads ligands docked by autodock vina.
Autodock vina writes outputs to disk in a PDBQT file format. This
PDBQT file can contain multiple docked “poses”. Recall that a pose
is an energetically favorable 3D conformation of a molecule. This
utility function reads and loads the structures for multiple poses
from vina’s output file.
Parameters:
pdbqt_output (str) – Should be the filename of a file generated by autodock vina’s
docking software.
Returns:
Tuple of molecules, scores. molecules is a list of rdkit
molecules with 3D information. scores is the associated vina
score.
This prepares protein-ligand complexes for docking.
Autodock Vina requires PDB files for proteins and ligands with
sensible inputs. This function uses PDBFixer and RDKit to ensure
that inputs are reasonable and ready for docking. Default values
are given for convenience, but fixing PDB files is complicated and
human judgement is required to produce protein structures suitable
for docking. Always inspect the results carefully before trying to
perform docking.
Parameters:
protein (str) – Filename for protein PDB file or a PDBID.
ligand (str) – Either a filename for a ligand PDB file or a SMILES string.
replace_nonstandard_residues (bool (default True)) – Replace nonstandard residues with standard residues.
remove_heterogens (bool (default True)) – Removes residues that are not standard amino acids or nucleotides.
remove_water (bool (default True)) – Remove water molecules.
add_hydrogens (bool (default True)) – Add missing hydrogens at the protonation state given by pH.
pH (float (default 7.0)) – Most common form of each residue at given pH value is used.
optimize_ligand (bool (default True)) – If True, optimize ligand with RDKit. Required for SMILES inputs.
pdb_name (Optional[str]) – If given, write sanitized protein and ligand to files called
“pdb_name.pdb” and “ligand_pdb_name.pdb”
Returns:
Tuple of protein_molecule, ligand_molecule with 3D information.
The printing threshold controls how many dataset elements are printed
when dc.data.Dataset objects are converted to strings or
represnted in the IPython repl.
If a dataset is large, printing self.ids as part of a string
representation can be very slow. This field controls the maximum
size for a dataset before ids are no longer printed.
Returns:
max_print_size – Maximum length of a dataset for ids to be printed in string
representation.
If a dataset is large, printing self.ids as part of a string
representation can be very slow. This field controls the maximum
size for a dataset before ids are no longer printed.
Parameters:
max_print_size (int) – Maximum length of a dataset for ids to be printed in string
representation.
The utilities here are used to sample electrons in a given molecule
and update it using monte carlo methods, which can be used for methods
like Variational Monte Carlo, etc.
This class enables to initialize electron’s position using gauss distribution around a nucleus and update using Markov Chain Monte-Carlo(MCMC) moves.
Using the probability obtained from the square of magnitude of wavefunction of a molecule/atom, MCMC steps can be performed to get the electron’s positions and further update the wavefunction.
This method is primarily used in methods like Variational Monte Carlo to sample electrons around the nucleons.
Sampling can be done in 2 ways:
-Simultaneous: All the electrons’ positions are updated all at once.
-Single-electron: MCMC steps are performed only a particular electron, given their index value.
Further these moves can be done in 2 methods:
-Symmetric: In this configuration, the standard deviation for all the steps are uniform.
-Asymmetric: In this configuration, the standard deviation are not uniform and typically the standard deviation is obtained a function like harmonic distances, etc.
Irrespective of these methods, the initialization is done uniformly around the respective nucleus and the number of electrons specified.
central_value (np.ndarray) – Contains each nucleus’ coordinates in a 2D array. The shape of the array should be(number_of_nucleus,3).Ex: [[1,2,3],[3,4,5],..]
f (Callable[[np.ndarray],np.ndarray]) – A function that should give the twice the log probability of wavefunction of the molecular system when called. Should taken in a 4D array of electron’s positions(x) as argument and return a numpy array containing the log probabilities of each batch.
batch_no (int, optional (default 10)) – Number of batches of the electron’s positions to be initialized.
x (np.ndarray, optional (default np.ndarray([]))) – Contains the electron’s coordinates in a 4D array. The shape of the array should be(batch_no,no_of_electrons,1,3). Can be a 1D empty array, when electron’s positions are yet to be initialized.
steps (int, optional (default 10)) – The number of MCMC steps to be performed when the moves are called.
steps_per_update (int (default 10)) – The number of steps after which the parameters of the MCMC gets updated.
seed (int, optional (default None)) – Random seed to use.
symmetric (bool, optional(default True)) – If true, symmetric moves will be used, else asymmetric moves will be followed.
simultaneous (bool, optional(default True)) – If true, MCMC steps will be performed on all the electrons, else only a single electron gets updated.
Calculates the harmonic mean of the value ‘y’ from the self.central value. The numpy array returned is typically scaled up to get the standard deviation matrix.
Parameters:
y (np.ndarray) – Containing the data distribution. Shape of y should be (batch,no_of_electron,1,3)
Returns:
Contains the harmonic mean of the data distribution of each batch. Shape of the array obtained (batch_no, no_of_electrons,1,1)
Initializes the position around a central value as mean sampled from a gauss distribution and updates self.x.
:param no_sample: Contains the number of samples to initialize under each mean. should be in the form [[3],[2]..], where here it means 3 samples and 2 samples around the first entry and second entry,respectively in self.central_value is taken.
:type no_sample: np.ndarray,
:param stddev: contains the stddev with which the electrons’ coordinates are initialized
:type stddev: float, optional (default 0.02)
Performs Metropolis-Hasting move for self.x(electrons). The type of moves to be followed -(simultaneous or single-electron, symmetric or asymmetric) have been specified when calling the class.
The self.x array is replaced with a new array at the end of each step containing the new electron’s positions.
Parameters:
asymmetric_func (Callable[[np.ndarray],np.ndarray], optional(default None)) – Should be specified for an asymmetric move.The function should take in only 1 argument- y: a numpy array wrt to which mean should be calculated.
This function should return the mean for the asymmetric proposal. For ferminet, this function is the harmonic mean of the distance between the electron and the nucleus.
stddev (float, optional (default 0.02)) – Specifies the standard deviation in the case of symmetric moves and the scaling factor of the standard deviation matrix in the case of asymmetric moves.
index (int, optional (default None)) – Specifies the index of the electron to be updated in the case of a single electron move.
Lattice is an object that describe the periodicity of the lattice.
Note that this object does not know about atoms.
For the integrated object between the lattice and atoms, please see Sol
estimate the ewald’s sum eta for nuclei interaction energy the
precision is assumed to be relative precision this formula is obtained
by estimating the sum as an integral.
Parameters:
precision (float) – The precision of the ewald’s sum.
Data structure that contains local information about density profiles.
Data structure used as a umbrella class for density profiles and the
derivative of the potential w.r.t. density profiles.
value (torch.Tensor) – Tensors containing the value of the local information.
grad (torch.Tensor or None) – If tensor, it represents the gradient of the local information with
shape (...,3) where ... should be the same shape as value.
lapl (torch.Tensor or None) – If tensor, represents the laplacian value of the local information.
It should have the same shape as value.
kin (torch.Tensor or None) – If tensor, represents the local kinetic energy density.
It should have the same shape as value.
This is the base class for the exchange-correlation (XC) functional.
The XC functional is used to calculate the exchange-correlation energy
and potential. The XC functional is usually divided into three families:
LDA, GGA, and Meta-GGA. The LDA is the simplest one, which only depends
on the density. The GGA depends on the density and its gradient. The
Meta-GGA depends on the density, its gradient, and its Laplacian.
Returns the xc energy density (energy per unit volume)
Parameters:
densinfo (Union[ValGrad, SpinParam[ValGrad]]) – The density information.
If the XC is unpolarized, then densinfo is ValGrad.
If the XC is polarized, then densinfo is SpinParam[ValGrad].
The ValGrad contains the value and gradient of the density.
The SpinParam[ValGrad] contains the value and gradient of the density
for each spin channel.
Returns the ValGrad for the xc potential given the density info
for unpolarized case.
This is the default implementation of vxc if there is no implementation
in the specific class of XC.
Parameters:
densinfo (Union[ValGrad, SpinParam[ValGrad]]) – The density information.
If the XC is unpolarized, then densinfo is ValGrad.
If the XC is polarized, then densinfo is SpinParam[ValGrad].
The ValGrad contains the value and gradient of the density.
The SpinParam[ValGrad] contains the value and gradient of the density
for each spin channel.
Returns:
The ValGrad for the xc potential.
If the XC is unpolarized, then the return is ValGrad.
If the XC is polarized, then the return is SpinParam[ValGrad].
This method should list tensor names that affect the output of the
method with name indicated in methodname.
If the methodname is not on the list in this function, it should
raise KeyError.
Parameters:
methodname (str) – The name of the method of the class.
prefix (str) – The prefix to be appended in front of the parameters name.
This usually contains the dots.
Returns:
Sequence of name of parameters affecting the output of the method.
Return type:
List[str]
Raises:
KeyError – If the list in this function does not contain methodname.
Returns the ValGrad for the xc potential given the density info
for unpolarized case.
Parameters:
densinfo (Union[ValGrad, SpinParam[ValGrad]]) – The density information.
If the XC is unpolarized, then densinfo is ValGrad.
If the XC is polarized, then densinfo is SpinParam[ValGrad].
The ValGrad contains the value and gradient of the density.
The SpinParam[ValGrad] contains the value and gradient of the density
for each spin channel.
Returns:
The ValGrad for the xc potential.
If the XC is unpolarized, then the return is ValGrad.
If the XC is polarized, then the return is SpinParam[ValGrad].
Returns the xc energy density (energy per unit volume)
Parameters:
densinfo (Union[ValGrad, SpinParam[ValGrad]]) – The density information.
If the XC is unpolarized, then densinfo is ValGrad.
If the XC is polarized, then densinfo is SpinParam[ValGrad].
The ValGrad contains the value and gradient of the density.
The SpinParam[ValGrad] contains the value and gradient of the density
for each spin channel.
This method should list tensor names that affect the output of the
method with name indicated in methodname.
If the methodname is not on the list in this function, it should
raise KeyError.
Parameters:
methodname (str) – The name of the method of the class.
prefix (str) – The prefix to be appended in front of the parameters name.
This usually contains the dots.
Returns:
Sequence of name of parameters affecting the output of the method.
Return type:
List[str]
Raises:
KeyError – If the list in this function does not contain methodname.
Returns the ValGrad for the xc potential given the density info
for unpolarized case.
Parameters:
densinfo (Union[ValGrad, SpinParam[ValGrad]]) – The density information.
If the XC is unpolarized, then densinfo is ValGrad.
If the XC is polarized, then densinfo is SpinParam[ValGrad].
The ValGrad contains the value and gradient of the density.
The SpinParam[ValGrad] contains the value and gradient of the density
for each spin channel.
Returns:
The ValGrad for the xc potential.
If the XC is unpolarized, then the return is ValGrad.
If the XC is polarized, then the return is SpinParam[ValGrad].
Returns the xc energy density (energy per unit volume)
Parameters:
densinfo (Union[ValGrad, SpinParam[ValGrad]]) – The density information.
If the XC is unpolarized, then densinfo is ValGrad.
If the XC is polarized, then densinfo is SpinParam[ValGrad].
The ValGrad contains the value and gradient of the density.
The SpinParam[ValGrad] contains the value and gradient of the density
for each spin channel.
This method should list tensor names that affect the output of the
method with name indicated in methodname.
If the methodname is not on the list in this function, it should
raise KeyError.
Parameters:
methodname (str) – The name of the method of the class.
prefix (str) – The prefix to be appended in front of the parameters name.
This usually contains the dots.
Returns:
Sequence of name of parameters affecting the output of the method.
Return type:
List[str]
Raises:
KeyError – If the list in this function does not contain methodname.
BaseDF represents the density fitting object used in calculating the
electron repulsion (and xc energy) in Hamiltonian.
Density fitting in density functional theory (DFT) is a technique used to
reduce the computational cost of evaluating electron repulsion integrals.
In DFT, the key quantity is the electron density rather than the wave
function, and the electron repulsion integrals involve four-electron
interactions, making them computationally demanding.
Density fitting exploits the fact that many-electron integrals can be
expressed as a sum of two-electron integrals involving auxiliary basis
functions. By approximating these auxiliary basis functions, often referred
to as fitting functions, the computational cost can be significantly reduced.
Hamilton is a class that provides the LinearOperator of the Hamiltonian
components.
The Hamiltonian represents the total energy operator for a system of
interacting electrons. The Kohn-Sham DFT approach introduces a set of
fictitious non-interacting electrons that move in an effective potential.
The total energy functional, which includes the kinetic energy of these
fictitious electrons and their interaction with an effective potential
(including the electron-electron interaction), is minimized to obtain the
ground-state electronic structure.
The Kohn-Sham Hamiltonian is a key component of this approach, representing
the operator that governs the evolution of the Kohn-Sham orbitals. It
includes terms for the kinetic energy of electrons, the external potential
(usually from nuclei), and the exchange-correlation potential that accounts
for the electron-electron interactions.
The Fock matrix represents the one-electron part of the Hamiltonian matrix. Its
components include kinetic energy, nuclear attraction, and electron-electron
repulsion integrals. The Fock matrix is pivotal in solving the electronic
Schrödinger equation and determining the electronic structure of molecular
systems.
Setup the basis (with its grad) in the spatial grid and prepare the
gradient of atomic orbital according to the ones required by the xc.
If xc is not given, then only setup the grid with ao (without any
gradients of ao)
Parameters:
grid (BaseGrid) – Grid used to setup this Hamilton.
xc (Optional[BaseXC] (default None)) – Exchange Corelation functional of this Hamiltonian.
Nuclear Coulomb attraction is the electrostatic force binding electrons
to a nucleus. Positively charged protons attract negatively charged
electrons, creating stability in quantum systems. This force plays a
fundamental role in determining the structure and behavior of atoms,
contributing significantly to the overall potential energy in atomic
physics.
Returns:
LinearOperator of the nuclear Coulomb attraction. Shape: (*BH, nao, nao)
Returns the LinearOperator of the one-electron operator (i.e. kinetic
and nuclear attraction). Action of a LinearOperator on a function is a
linear transformation. In the case of one-electron operators, these
transformations are essential for solving the Schrödinger equation and
understanding the behavior of electrons in an atomic or molecular system.
Returns:
LinearOperator of the one-electron operator. Shape: (*BH, nao, nao)
Returns the LinearOperator representing the overlap of the basis.
The overlap of the basis refers to the degree to which atomic or
molecular orbitals in a quantum mechanical system share common space.
Returns:
LinearOperator representing the overlap of the basis.
Shape: (*BH, nao, nao)
Obtains the LinearOperator of the Coulomb electron repulsion operator.
Known as the J-matrix.
In the context of electronic structure theory, it accounts for the
repulsive interaction between electrons in a many-electron system. The
J-matrix elements involve the Coulombic interactions between pairs of
electrons, influencing the total energy and behavior of the system.
Parameters:
dm (torch.Tensor) – Density matrix. Shape: (*BD, nao, nao)
Returns:
LinearOperator of the Coulomb electron repulsion operator.
Shape: (*BDH, nao, nao)
Obtains the LinearOperator of the exchange operator.
It is -0.5 * K where K is the K matrix obtained from 2-electron integral.
Exchange operator is a mathematical representation of the exchange
interaction between identical particles, such as electrons. The
exchange operator quantifies the effect of interchanging the
positions of two particles.
Parameters:
dm (Union[torch.Tensor, SpinParam[torch.Tensor]]) – Density matrix. Shape: (*BD, nao, nao)
Returns:
LinearOperator of the exchange operator. Shape: (*BDH, nao, nao)
External potential energy that a particle experiences in a discretized
space or grid. In quantum mechanics or computational physics, when
solving for the behavior of particles, an external potential is often
introduced to represent the influence of external forces.
Parameters:
vext (torch.Tensor) – External potential in the grid. Shape: (*BR, ngrid)
Returns:
LinearOperator of the external potential in the grid. Shape: (*BRH, nao, nao)
Returns a LinearOperator for the exchange-correlation potential
The exchange-correlation potential combines two effects:
1. Exchange potential: Arises from the antisymmetry of the electron
wave function. It quantifies the tendency of electrons to avoid each
other due to their indistinguishability.
2. Correlation potential: Accounts for the electron-electron
correlation effects that arise from the repulsion between electrons.
TODO: check if what we need for Meta-GGA involving kinetics and for
exact-exchange
Parameters:
dm (Union[torch.Tensor, SpinParam[torch.Tensor]]) – Density matrix. Shape: (*BD, nao, nao)
Returns:
LinearOperator for the exchange-correlation potential. Shape: (*BDH, nao, nao)
Convert the atomic orbital free parameters (parametrized in such a way
so it is not bounded) to the density matrix.
Parameters:
ao_orb_params (torch.Tensor) – The tensor that parametrized atomic orbital in an unbounded space.
ao_orb_coeffs (torch.Tensor) – The tensor that helps ao_orb_params in describing the orbital.
The difference with ao_orb_params is that ao_orb_coeffs is
not differentiable and not to be optimized in variational method.
orb_weight (torch.Tensor) – The orbital weights.
with_penalty (float or None) – If a float, it returns a tuple of tensors where the first element is
dm, and the second element is the penalty multiplied by the
penalty weights. The penalty is to compensate the overparameterization
of ao_orb_params, stabilizing the Hessian for gradient calculation.
Returns:
The density matrix from the orbital parameters and (if with_penalty)
the penalty of the overparameterization of ao_orb_params.
Return type:
torch.Tensor or tuple of torch.Tensor
Notes
The penalty should be 0 if ao_orb_params is from dm2ao_orb_params.
The density matrix should be recoverable when put through dm2ao_orb_params
and ao_orb_params2dm.
Convert from the density matrix to the orbital parameters.
The map is not one-to-one, but instead one-to-many where there might
be more than one orbital parameters to describe the same density matrix.
For restricted systems, only one of the dm (dm.u or dm.d) is
sufficient.
Parameters:
dm (torch.Tensor) – The density matrix.
norb (int) – The number of orbitals for the system.
Returns:
The atomic orbital parameters for the first returned value and the
atomic orbital coefficients for the second value.
qc (BaseQCCalc) – object often acts as a wrapper around an engine class (from dqc.qccalc) that contains information about the self-consistent iterations.
References
Kasim, Muhammad F., and Sam M. Vinko. “Learning the exchange-correlation functional from nature with fully differentiable density functional theory.” Physical Review Letters 127.12 (2021): 126403.
https://github.com/diffqc/dqc/blob/master/dqc/qccalc/ks.py
Both interacting and non-interacting system’s total energy can be expressed in terms of the density matrix. The ground state properties of a system can be calculated by minimizing the energy w.r.t the density matrix.
Interface to DQC’s BaseGrid class. BaseGrid is a class that regulates the integration points over the spatial
dimensions.
:param qc: object often acts as a wrapper around an engine class (from dqc.qccalc) that contains information about the self-consistent iterations.
:type qc: BaseQCCalc
Obtain the torch.tensor containing the dV elements for the integration.
:returns: The dV elements for the integration. *BG is the length of the BaseGrid.
:rtype: torch.tensor (*BG, ngrid)
Returns the grid points position in the specified coordinate in
self.coord_type.
:returns: The grid points position. *BG is the length of the BaseGrid.
:rtype: torch.tensor (*BG, ngrid, ndim)
Return a list with the parameter names corresponding to the given method
(methodname)
:returns: List of parameter names of methodname
:rtype: List[str]
Quantum Chemistry calculation. This class is the interface to the users
regarding parameters that can be calculated after the self-consistent
iterations (or other processes).
References
Kasim, Muhammad F., and Sam M. Vinko. “Learning the exchange-correlation
functional from nature with fully differentiable density functional
theory.” Physical Review Letters 127.12 (2021): 126403.
https://github.com/diffqc/dqc/blob/master/dqc/utils/datastruct.py
Run the calculation.
Note that this method can be invoked several times for one object to
try for various self-consistent options to reach convergence.
Returns the density matrix in atomic orbital. For polarized case, it
returns a SpinParam of 2 tensors representing the density matrices for
spin-up and spin-down.
The parameters that corresponds to the spin-down electrons.
Type:
any type
References
Kasim, Muhammad F., and Sam M. Vinko. “Learning the exchange-correlation
functional from nature with fully differentiable density functional
theory.” Physical Review Letters 127.12 (2021): 126403.
https://github.com/diffqc/dqc/blob/master/dqc/utils/datastruct.py
Convert the parameters & coefficients to the orthogonal orbitals.
params is the tensor to be optimized in variational method, while
coeffs is a tensor that is needed to get the orbital, but it is not
optimized in the variational method.
Parameters:
params (torch.Tensor) – The free parameters to be optimized.
coeffs (torch.Tensor) – The coefficients to get the orthogonal orbitals.
with_penalty (float (default 0.0)) – If not 0.0, return the penalty term for the free parameters.
Returns:
orb (torch.Tensor) – The orthogonal orbitals.
penalty (torch.Tensor) – The penalty term for the free parameters. If with_penalty is 0.0,
this is not returned.
Convert the parameters & coefficients to the orthogonal orbitals.
params is the tensor to be optimized in variational method, while
coeffs is a tensor that is needed to get the orbital, but it is not
optimized in the variational method.
Parameters:
params (torch.Tensor) – The free parameters to be optimized.
coeffs (torch.Tensor) – The coefficients to get the orthogonal orbitals.
with_penalty (float (default 0.0)) – If not 0.0, return the penalty term for the free parameters.
Returns:
orb (torch.Tensor) – The orthogonal orbitals.
penalty (torch.Tensor) – The penalty term for the free parameters. If with_penalty is 0.0,
this is not returned.
Convert the parameters & coefficients to the orthogonal orbitals.
params is the tensor to be optimized in variational method, while
coeffs is a tensor that is needed to get the orbital, but it is not
optimized in the variational method.
Parameters:
params (torch.Tensor) – The free parameters to be optimized. (*, nparams)
coeffs (torch.Tensor) – The coefficients to get the orthogonal orbitals. (*, nao, norb)
with_penalty (float (default 0.0)) – If not 0.0, return the penalty term for the free parameters.
Returns:
orb (torch.Tensor) – The orthogonal orbitals.
penalty (torch.Tensor) – The penalty term for the free parameters. If with_penalty is 0.0,
this is not returned.
System is a class describing the environment before doing the quantum
chemistry calculation. It contains the information of the atoms, the
external electric field, the spin, the charge, etc. It also contains the
Hamiltonian object and the grid object for the calculation. The system
object is also responsible for setting up the cache for the parameters
that can be read/written from/to the cache file.
Set up the cache to read/write some parameters from the given files.
If paramnames is not given, then read/write all cache-able parameters
specified by each class.
Parameters:
fname (str) – The file name of the cache file.
paramnames (Optional[List[str]] (default None)) – The list of parameter names to read/write from the cache file.
Returns the atomic orbital weights. If polarized == False, then it
returns the total orbital weights. Otherwise, it returns a tuple of
orbital weights for spin-up and spin-down.
Parameters:
polarized (bool (default False)) – Whether to return the orbital weights for each spin.
grid_integrator (str (default "chebyshev")) – The grid integrator to use. Available options are “chebyshev”,
“chebyshev2”, and “uniform”.
grid_transform (Union[str, BaseGridTransform] (default "logm3")) – The grid transformation to use. Available options are “logm3”,
“de2”, and “treutlerm4”.
dtype (torch.dtype, optional (default torch.float64)) – The data type to use for the grid.
device (torch.device, optional (default torch.device('cpu'))) – The device to use for the grid.
Base class for grid transformation
Grid transformation is to transform the integration from the coordinate of
grid_integrator to the actual coordinate.
It is used as a base class for other grid transformations.
x2r and get_drdx are abstract methods that need to be implemented.
To use this class, the user must implement the getparamnames method
which returns a list of tensor names that affect the output of the method
with name indicated in methodname.
Used in:
Classes of Density Functional Theory (DFT).
It can also be used in other classes that need to be converted to pure
functions for higher order derivatives purpose.
This method should list tensor names that affect the output of the
method with name indicated in methodname.
If the methodname is not on the list in this function, it should
raise KeyError.
Parameters:
methodname (str) – The name of the method of the class.
prefix (str) – The prefix to be appended in front of the parameters name.
This usually contains the dots.
Returns:
Sequence of name of parameters affecting the output of the method.
Return type:
List[str]
Raises:
KeyError – If the list in this function does not contain methodname.
Set the input parameters to the object’s parameters to make a copy of
the operations. The input parameters are unique parameters, i.e. they
are not necessarily the same tensors as the object’s parameters.
Note: This function can only be run after running getuniqueparams.
Parameters:
methodname (str) – The name of the method of the class.
*uniqueparams – The parameters to be set to the object’s parameters. The number of
parameters must be the same as the number of unique parameters
returned by getuniqueparams.
Returns:
The number of parameters that are set to the object’s parameters.
Perform a rigorous check on the implemented getparamnames
in the class for a given method and its parameters as well as keyword
Parameters.
It raises warnings if there are missing or excess parameters in the
getparamnames implementation.
Parameters:
method (Callable) – The method of this class to be tested
LinearOperator is a base class designed to behave as a linear operator
without explicitly determining the matrix. This LinearOperator should
be able to operate as batched linear operators where its shape is
(B1,B2,...,Bb,p,q) with B* as the (optional) batch dimensions.
For a user-defined class to behave as LinearOperator, it must use
LinearOperator as one of the parent and it has to have ._mv()
method implemented and ._getparamnames() if used in xitorch’s
functionals with torch grad enabled.
Class method to wrap a matrix into LinearOperator.
Parameters:
mat (torch.Tensor) – Matrix to be wrapped in the LinearOperator.
is_hermitian (bool or None) – Indicating if the matrix is Hermitian. If None, the symmetry
will be checked. If supplied as a bool, there is no check performed.
Returns:
Linear operator object that represents the matrix.
Apply the matrix-vector operation to vector x with shape (...,q).
The batch dimensions of x need not be the same as the batch dimensions
of the LinearOperator, but it must be broadcastable.
Parameters:
x (torch.tensor) – The vector with shape (...,q) where the linear operation is operated on
Returns:
y – The result of the linear operation with shape (...,p)
Apply the matrix-matrix operation to matrix x with shape (...,q,r).
The batch dimensions of x need not be the same as the batch dimensions
of the LinearOperator, but it must be broadcastable.
Parameters:
x (torch.tensor) – The matrix with shape (...,q,r) where the linear operation is
operated on.
Returns:
y – The result of the linear operation with shape (...,p,r)
Apply the matrix-vector adjoint operation to vector x with shape (...,p),
i.e. A^Hx.
The batch dimensions of x need not be the same as the batch dimensions
of the LinearOperator, but it must be broadcastable.
Parameters:
x (torch.tensor) – The vector of shape (...,p) where the adjoint linear operation is operated at.
Returns:
y – The result of the adjoint linear operation with shape (...,q)
Apply the matrix-matrix adjoint operation to matrix x with shape (...,p,r),
i.e. A^HX.
The batch dimensions of x need not be the same as the batch dimensions
of the LinearOperator, but it must be broadcastable.
Parameters:
x (torch.Tensor) – The matrix of shape (...,p,r) where the adjoint linear operation is operated on.
Returns:
y – The result of the adjoint linear operation with shape (...,q,r).
This is used to calculate the adjoint of a LinearOperator without
explicitly constructing the adjoint matrix. This is useful when the
adjoint matrix is not explicitly constructed, e.g. when the LinearOperator
is a function of other parameters.
is_hermitian (bool) – Indicating if the matrix is Hermitian. If None, the symmetry
will be checked. If supplied as a bool, there is no check performed.
PureFunction class wraps methods to make it stateless and expose the pure
function to take inputs of the original inputs (params) and the object’s
states (objparams).
For functions, this class only acts as a thin wrapper.
Restore stack stores list of (objparams, identical) everytime the objparams
are set, it will store the old objparams and indication if the old and new
objparams are identical.
For Using this Class we first need to implement _get_all_obj_params_init
and _set_all_obj_params.
PureFunction class wraps methods to make it stateless and expose the pure
function to take inputs of the original inputs (params) and the object’s
states (objparams).
For functions, this class only acts as a thin wrapper.
Restore stack stores list of (objparams, identical) everytime the objparams
are set, it will store the old objparams and indication if the old and new
objparams are identical.
For Using this Class we first need to implement _get_all_obj_params_init
and _set_all_obj_params.
A (LinearOperator) – The linear operator A to be solved. Shape: (*BA, na, na)
B (torch.Tensor) – Batched matrix B. Shape: (*BB, na, ncols)
E (torch.Tensor or None) – Batched vector E. Shape: (*BE, ncols)
M (LinearOperator or None) – The linear operator M. Shape: (*BM, na, na)
posdef (bool or None) – Indicating if the operation \(\mathbf{AX-MXE}\) a positive
definite for all columns and batches.
If None, it will be determined by power iterations.
max_niter (int or None) – Maximum number of iteration. If None, it is set to int(1.5*A.shape[-1])
rtol (float) – Relative tolerance for stopping condition w.r.t. norm of B
atol (float) – Absolute tolerance for stopping condition w.r.t. norm of B
eps (float) – Substitute the absolute zero in the algorithm’s denominator with this
value to avoid nan.
This function computes the sum of values along segments within a tensor. It is useful when you have a tensor with segment IDs and you want to compute the sum of values for each segment.
This function is analogous to tf.segment_sum. (https://www.tensorflow.org/api_docs/python/tf/math/segment_sum).
Parameters:
data (torch.Tensor) – A pytorch tensor containing the values to be summed. It can have any shape, but its rank (number of dimensions) should be at least 1.
segment_ids (torch.Tensor) – A 1-D tensor containing the indices for the segmentation. The segments can be any non-negative integer values, but they must be sorted in non-decreasing order.
Returns:
out_tensor – Tensor with the same shape as data, where each value corresponds to the sum of values within the corresponding segment.
Convert a tensor to Fortran order. (The last two dimensions are made Fortran order.)
Fortran order/ array is a special case in which all elements of an array are stored in
column-major order.
Computes the values for different Feature on given batch.
It works as a helper function to coulomb matrix.
This function takes in a batch of Molecules represented as Coulomb Matrix.
It proceeds as follows:
It calculates the Number of atoms per molecule by counting all the non zero elements(numbers) of every molecule layer in matrix in one dimension.
The Gaussian distance is calculated using the Euclidean distance between the Cartesian coordinates of two atoms. The distance value is then passed through a Gaussian function, which transforms it into a continuous value.
Then using number of atom per molecule, calculates the atomic charge by looping over the molecule layer in the Coulomb matrix and takes the 2.4 root of the diagonal of 2X of each molecule layer. Undoing the Equation of coulomb matrix.
Atom_membership is assigned as a commomn repeating integers for all the atoms for a specific molecule.
Distance Membership encodes spatial information, assigning closer values to atoms that are in that specific molecule. All initial Distances are added a start value to them which are unique to each molecule.
Models Used in:
DTNN
Parameters:
X_b (np.ndarray) – It is a 3d Matrix containing information of each the atom’s ionic interaction with other atoms in the molecule.
distance_min (float (default -1)) – minimum distance of atom pairs (in Angstrom)
distance_max (float (default = 18)) – maximum distance of atom pairs (in Angstrom)
n_distance (int (default 100)) – granularity of distance matrix
step size will be (distance_max-distance_min)/n_distance
Returns:
atom_number (np.ndarray) – Atom numbers are assigned to each atom based on their atomic properties.
The atomic numbers are derived from the periodic table of elements.
For example, hydrogen -> 1, carbon -> 6, and oxygen -> 8.
gaussian_dist (np.ndarray) – Gaussian distance refers to the method of representing the pairwise distances between atoms in a molecule using Gaussian functions.
The Gaussian distance is calculated using the Euclidean distance between the Cartesian coordinates of two atoms.
The distance value is then passed through a Gaussian function, which transforms it into a continuous value.
atom_mem (np.ndarray) – Atom membership refers to the binary representation of whether an atom belongs to a specific group or property within a molecule.
It allows the model to incorporate domain-specific information and enhance its understanding of the molecule’s properties and interactions.
dist_mem_i (np.ndarray) – Distance membership i are utilized to encode spatial information and capture the influence of atom distances on the properties and interactions within a molecule.
The inner membership function assigns higher values to atoms that are closer to the atoms’ interaction region, thereby emphasizing the impact of nearby atoms.
dist_mem_j (np.ndarray) – It captures the long-range effects and influences between atoms that are not in direct proximity but still contribute to the overall molecular properties.
Distance membership j are utilized to encode spatial information and capture the influence of atom distances on the properties and interactions outside a molecule.
The outer membership function assigns higher values to atoms that are farther to the atoms’ interaction region, thereby emphasizing the impact of farther atoms.
It creates a 2d Matrix empty matrix according to batch size and max_length.
Then iteratively fills it with the key-values from the input dictionary.
Many NLP Models like SeqToSeq has sentences as there inputs. We need to
convert these sentences into numbers so that the model can do computation
on them.
This function takes in the sentence then using the input_dict dictionary
picks up the words/letters equivalent numerical represntation. Then makes
an numpy array of it.
If the reverse_input is True, then the order of the input sequences is
reversed before sending them into the encoder. This can improve performance
when working with long sequences.
These values can be used to generate embeddings for further processing.
Models used in:
SeqToSeq
Parameters:
sequences (Collection) – List of sequences to be converted into input array.
reverse_input (bool) – If True, reverse the order of input sequences before sending them into
the encoder. This can improve performance when working with long sequences.
batch_size (int) – Batch size of the input array.
input_dict (dict) – Dictionary containing the key-value pairs of input sequences.
end_mark (Any) – End mark for the input sequences.
Returns:
features – Numeric Representation of the given sequence according to input_dict.
It creates a 2d Matrix empty matrix according to batch size and max_length.
Then iteratively fills it with the key-values from the output dictionary.
This function is similar to create_input_array function. The only
difference is that it is used for output sequences and does not have the
reverse_input parameter as it is not required for output sequences.
It is used in NLP Models like SeqToSeq where the output is also a sentence
and we need to convert it into numbers so that the model can do computation
on them. This function takes in the sentence then using the output_dict
dictionary picks up the words/letters equivalent numerical represntation.
Then makes an numpy array of it.
These values can be used to generate embeddings for further processing.
Models used in:
SeqToSeq
Parameters:
sequences (Collection) – List of sequences to be converted into output array.
max_output_length (bool) – Maximum length of output sequence that may be generated
batch_size (int) – Batch size of the output array.
output_dict (dict) – Dictionary containing the key-value pairs of output sequences.
end_mark (Any) – End mark for the output sequences.
Returns:
features – Numeric Representation of the given sequence according to output_dict.
The utilities here refer to equivariance tools that play a vital
role in mathematics and applied sciences. They excel in preserving
the relationships between objects or data points when undergoing transformations
such as rotations or scaling.
You can refer to the tutorials
for additional information regarding equivariance and Deepchem’s support for equivariance.
Generate the generators of the special unitary group SU(2) in a given representation.
The function computes the generators of the SU(2) group for a specific representation
determined by the value of ‘k’. These generators are commonly used in the study of
quantum mechanics, angular momentum, and related areas of physics and mathematics.
The generators are represented as matrices.
The SU(2) group is a fundamental concept in quantum mechanics and symmetry theory.
The generators of the group, denoted as J_x, J_y, and J_z, represent the three
components of angular momentum operators. These generators play a key role in
describing the transformation properties of physical systems under rotations.
The returned tensor contains three matrices corresponding to the x, y, and z generators,
usually denoted as J_x, J_y, and J_z. These matrices form a basis for the Lie algebra
of the SU(2) group.
In linear algebra, specifically within the context of quantum mechanics, lowering and
raising operators are fundamental concepts that play a crucial role in altering the
eigenvalues of certain operators while acting on quantum states. These operators are
often referred to collectively as “ladder operators.”
A lowering operator is an operator that, when applied to a quantum state, reduces the
eigenvalue associated with a particular observable. In the context of SU(2), the lowering
operator corresponds to J_-.
Conversely, a raising operator is an operator that increases the eigenvalue of an
observable when applied to a quantum state. In the context of SU(2), the raising operator
corresponds to J_+.
The z-generator matrix represents the component of angular momentum along the z-axis,
often denoted as J_z. It commutes with both J_x and J_y and is responsible for quantizing
the angular momentum.
Note that the dimensions of the returned tensor will be (3, 2j+1, 2j+1), where each matrix
has a size of (2j+1) x (2j+1).
:param k: The representation index, which determines the order of the representation.
:type k: int
Returns:
A stack of three SU(2) generators, corresponding to J_x, J_z, and J_y.
Return type:
torch.Tensor
Notes
A generating set of a group is a subset $S$ of the group $G$ such that every element
of $G$ can be expressed as a combination (under the group operation) of finitely many
elements of the subset $S$ and their inverses.
The special unitary group $SU_n(q)$ is the set of $n*n$ unitary matrices with determinant
+1. $SU(2)$ is homeomorphic with the orthogonal group $O_3^+(2)$. It is also called the
unitary unimodular group and is a Lie group.
Construct the generators of the SO(3) Lie algebra for a given quantum angular momentum.
The function generates the generators of the special orthogonal group SO(3), which represents the group
of rotations in three-dimensional space. Its Lie algebra, which consists of the generators of
infinitesimal rotations, is often used in physics to describe angular momentum operators.
The generators of the Lie algebra can be related to the SU(2) group, and this function uses
a transformation to convert the SU(2) generators to the SO(3) basis.
The primary significance of the SO(3) group lies in its representation of three-dimensional
rotations. Each matrix in SO(3) corresponds to a unique rotation, capturing the intricate
ways in which objects can be oriented in 3D space. This concept finds application in
numerous fields, ranging from physics to engineering.
Parameters:
k (int) – The representation index, which determines the order of the representation.
Returns:
A stack of three SO(3) generators, corresponding to J_x, J_z, and J_y.
Return type:
torch.Tensor
Notes
The special orthogonal group $SO_n(q)$ is the subgroup of the elements of general orthogonal
group $GO_n(q)$ with determinant 1. $SO_3$ (often written $SO(3)$) is the rotation group
for three-dimensional space.
These matrices are orthogonal, which means their rows and columns form mutually perpendicular
unit vectors. This preservation of angles and lengths makes orthogonal matrices fundamental
in various mathematical and practical applications.
The “special” part of $SO(3)$ refers to the determinant of these matrices being $+1$. The
determinant is a scalar value that indicates how much a matrix scales volumes.
A determinant of $+1$ ensures that the matrix represents a rotation in three-dimensional
space without involving any reflection or scaling operations that would reverse the orientation of space.
Construct a transformation matrix to change the basis from real to complex spherical harmonics.
This function constructs a transformation matrix Q that converts real spherical
harmonics into complex spherical harmonics.
It operates on the basis functions $Y_{ell m}$ and $Y_{ell}^{m}$, and accounts
for the relationship between the real and complex forms of these harmonics
as defined in the provided mathematical expressions.
The resulting transformation matrix Q is used to change the basis of vectors or tensors of real spherical harmonics to
their complex counterparts.
Parameters:
k (int) – The representation index, which determines the order of the representation.
dtype (torch.dtype, optional) – The data type for the output tensor. If not provided, the
function will infer it. Default is None.
device (torch.device, optional) – The device where the output tensor will be placed. If not provided,
the function will use the default device. Default is None.
Returns:
A transformation matrix Q that changes the basis from real to complex spherical harmonics.
Return type:
torch.Tensor
Notes
Spherical harmonics Y_l^m are a family of functions that are defined on the surface of a
unit sphere. They are used to represent various physical and mathematical phenomena that
exhibit spherical symmetry. The indices l and m represent the degree and order of the
spherical harmonics, respectively.
The conversion from real to complex spherical harmonics is achieved by applying specific
transformation coefficients to the real-valued harmonics. These coefficients are derived
from the properties of spherical harmonics.
References
Examples
# The transformation matrix generated is used to change the basis of a vector of
# real spherical harmonics with representation index 1 to complex spherical harmonics.
>>> change_basis_real_to_complex(1)
tensor([[-0.7071+0.0000j, 0.0000+0.0000j, 0.0000-0.7071j],
Wigner D matrix representation of the SO(3) rotation group.
The function computes the Wigner D matrix representation of the SO(3) rotation group
for a given representation index ‘k’ and rotation angles ‘alpha’, ‘beta’, and ‘gamma’.
The resulting matrix satisfies properties of the SO(3) group representation.
Parameters:
k (int) – The representation index, which determines the order of the representation.
alpha (torch.Tensor) – Rotation angles (in radians) around the Y axis, applied third.
beta (torch.Tensor) – Rotation angles (in radians) around the X axis, applied second.
gamma (torch.Tensor)) – Rotation angles (in radians) around the Y axis, applied first.
Returns:
The Wigner D matrix of shape (#angles, 2k+1, 2k+1).
Return type:
torch.Tensor
Notes
The Wigner D-matrix is a unitary matrix in an irreducible representation
of the groups SU(2) and SO(3).
The Wigner D-matrix is used in quantum mechanics to describe the action
of rotations on states of particles with angular momentum. It is a key
concept in the representation theory of the rotation group SO(3), and
it plays a crucial role in various physical contexts.
Gives indentation of the second line and next lines.
It is used to format the string representation of an object.
Which might be containing multiples objects in it.
Usage: LinearOperator
Parameters:
s (str) – The string to be indented.
nspace (int) – The number of spaces to be indented.