Overview
The Python API (or PyAPI for short) of MLatom mainly contains 3 components: mlatom.data
, mlatom.models
, and mlatom.simulations
.
With class mlatom.data
, one can create/manipulate/save/load chemical data into objects like mlatom.data.atom
, mlatom.data.molecule
, and mlatom.data.molecular_database
.
The class mlatom.models
contains lots of computational chemistry models, based on quantum mechanics and machine learning, for making predictions on molecules. The models can be categorized into 3 types:
methods: Models of methods that can be used ‘as is’ without the need to be trained by the user.
ml_model: Machine learning models that require user to train them.
model_tree_node: models consisting of other model objects (
mlatom.models.methods
,mlatom.models.ml_model
, or anothermlatom.models.model_tree_node
).
mlatom.simulations
makes use of an mlatom.models
object to perform simulations such as geometry optimizations or molecular dynamics.
Please check a simple example that illustrates the usage of these components.
Data
!---------------------------------------------------------------------------!
! data: Module for working with data !
! Implementations by: Pavlo O. Dral, Fuchun Ge, !
! Shuang Zhang, Yi-Fan Hou, Yanchi Ou !
!---------------------------------------------------------------------------!
- class mlatom.data.atom(nuclear_charge: int | None = None, atomic_number: int | None = None, element_symbol: str | None = None, nuclear_mass: float | None = None, xyz_coordinates: ndarray | List | None = None)[source]
Create an atom object.
- Parameters:
nuclear_charge (int, optional) – provide the nuclear charge to define the atom.
atomic_number (int, optional) – provide the atomic number to define the atom.
element_symbol (int, optional) – provide the element symbol to define the atom.
nuclear_mass (int, optional) – provide the nuclear mass to define the atom.
xyz_coordinates (Array-like, optional) – specify the location of atom in Cartesian coordinates.
- class mlatom.data.molecule(charge: int = 0, multiplicity: int = 1, atoms: List[atom] | None = None)[source]
Create a molecule object.
- Parameters:
charge (float, optional) – Specify the charge of the molecule.
multiplicity (int, optional) – Specify the multiplicity of the molecule.
atoms (List[
atom
], optional) – Specify the atoms in the molecule.
Examples
Select an atom inside with subscription:
from mlatom.data import atom, molecule at = atom(element_symbol = 'C') mol = molecule(atoms = [at]) print(id(at), id(mol[0]))
- id
The unique ID for this molecule.
- charge
The electric charge of the molecule.
- multiplicity
The multiplicity of the molecule.
- read_from_xyz_file(filename: str, format: str | None = None) molecule [source]
Load molecular geometry from XYZ file.
Data in standard XYZ format can be read if parameter
format
is not specified.Extra formats supoorted are:
'COLUMBUS'
'NEWTON-X'
or'NX'
- Parameters:
filename (str) – The name of the file to be read.
format (str, optional) – The format of the file.
- read_from_xyz_string(string: str | None = None, format: str | None = None) molecule [source]
Load molecular geometry from XYZ string.
Data in standard XYZ format can be read if parameter
format
is not specified.Extra formats supoorted are:
'COLUMBUS'
'NEWTON-X'
or'NX'
- Parameters:
string (str) – The string input.
format (str, optional) – The format of the string.
- read_from_numpy(coordinates: ndarray, species: ndarray) molecule [source]
Load molecular geometry from a numpy array of coordinates and another one for species.
The shape of the input
coordinates
should be(N, 3)
, while(N,)
for the inputspecies
.Where the
N
is the number of atoms.
- read_from_smiles_string(smi_string: str) molecule [source]
Generate molecular geometry from a SMILES string provided.
The geometry will be generated and optimized with Pybel’s
make3D()
method.
- classmethod from_xyz_file(filename: str, format: str | None = None) molecule [source]
Classmethod wrapper for
molecule.read_from_xyz_file()
, returns amolecule
object.
- classmethod from_xyz_string(string: str | None = None, format: str | None = None) molecule [source]
Classmethod wrapper for
molecule.read_from_xyz_string()
, returns amolecule
object.
- classmethod from_numpy(coordinates: ndarray, species: ndarray) molecule [source]
Classmethod wrapper for
molecule.read_from_numpy()
, returns amolecule
object.
- classmethod from_smiles_string(smi_string: str) molecule [source]
Classmethod wrapper for
molecule.read_from_smiles_string()
, returns amolecule
object.
- add_atom_from_xyz_string(line: str) None [source]
Add an atom to molecule from a string in XYZ format
- add_scalar_property(scalar, property_name: str = 'y') None [source]
Add a scalar property to the molecule. So the property can be called by molecule.<property_name>.
- Parameters:
scalar – The scalar to be added.
property_name (str, optional) – The name assign to the scalar property.
- add_xyz_derivative_property(derivative, property_name: str = 'y', xyz_derivative_property: str = 'xyz_derivatives') None [source]
Add a XYZ derivative property to the molecule.
- Parameters:
derivative – The derivative property to be added.
property_name (str, optional) – The name of the associated non-derivative property.
xyz_derivative_property (str, optional) – the name assign to the derivative property.
- add_xyz_vectorial_property(vector, xyz_vectorial_property: str = 'xyz_vector') None [source]
Add a XYZ vectorial property to the molecule.
- Parameters:
vector – The vector to be added.
xyz_vectorial_property (str, optional) – the name assign to the vectorial property.
- write_file_with_xyz_coordinates(filename: str, format: str | None = None) None [source]
Write the molecular geometry data into a file. Data in standard XYZ format can be read if parameter
format
is not specified.Extra formats supoorted are:
'COLUMBUS'
'NEWTON-X'
or'NX'
- Parameters:
filename (str) – The name of the file to be written.
format (str, optional) – The format of the file.
- property atomic_numbers: ndarray
The atomic numbers of the atoms in the molecule.
- property element_symbols: ndarray
The element symbols of the atoms in the molecule.
- property smiles: str
The SMILES representation of the molecule.
- property xyz_coordinates: ndarray
The XYZ geometry the molecule.
- property kinetic_energy: float
Give out the kinetic energy (A.U.) based on the xyz_velocities.
- class mlatom.data.molecular_database(molecules: List[molecule] | None = None)[source]
Create a database for molecule objects.
- Parameters:
molecules (List[
molecule
]) – A list of molecule to be included in the molecular database.
Examples
Select an atom inside with subscription:
from mlatom.data import atom, molecule, molecular_database at = atom(element_symbol = 'C') mol = molecule(atoms = [at]) molDB = molecular_database([mol]) print(id(mol) == id(molDB[0])) # the output should be 'True'
Slicing the database like a numpy array:
from mlatom.data import molecular_database molDB = molecular_database.from_xyz_file('devtests/al/h2_fci_db/xyz.dat') print(len(molDB)) # 451 print(len(molDB[:100:4])) # 25
- read_from_xyz_file(filename: str, append: bool = False) molecular_database [source]
Load molecular geometry from XYZ file.
- Parameters:
filename (str) – The name of the file to be read.
append (bool, optional) – Append to current database if True, otherwise clear the current database.
- read_from_xyz_string(string: str, append=False) molecular_database [source]
Load molecular geometry from XYZ string.
- Parameters:
string (str) – The name of the file to be read.
append (bool, optional) – Append to current database if True, otherwise clear the current database.
- read_from_numpy(coordinates: ndarray, species: ndarray, append: bool = False) molecular_database [source]
Load molecular geometries from a numpy array of coordinates and another one for species.
The shape of the input
coordinates
should be(M, N, 3)
, while(M, N,)
for the inputspecies
.Where the
N
is the number of atoms andM
is the number of molecules.
- read_from_smiles_file(smi_file: str, append: bool = False) molecular_database [source]
Generate molecular geometries from a SMILES file provided.
The geometries will be generated and optimized with Pybel’s
make3D()
method.
- read_from_smiles_string(smi_string: str, append: bool = False) molecular_database [source]
Generate molecular geometries from a SMILES string provided.
The geometries will be generated and optimized with Pybel’s
make3D()
method.
- classmethod from_xyz_file(filename: str) molecular_database [source]
Classmethod wrapper for
molecular_database.read_from_xyz_file()
, returns amolecular_database
object.
- classmethod from_xyz_string(string: str) molecular_database [source]
Classmethod wrapper for
molecular_database.read_from_xyz_string()
, returns amolecular_database
object.
- classmethod from_numpy(coordinates: ndarray, species: ndarray) molecular_database [source]
Classmethod wrapper for
molecular_database.read_from_numpy()
, returns amolecular_database
object.
- classmethod from_smiles_file(smi_file: str) molecular_database [source]
Classmethod wrapper for
molecular_database.read_from_smiles_file()
, returns amolecular_database
object.
- classmethod from_smiles_string(smi_string: str | List) molecular_database [source]
Classmethod wrapper for
molecular_database.read_from_smiles_string()
, returns amolecular_database
object.
- add_scalar_properties(scalars, property_name: str = 'y') None [source]
Add scalar properties to the molecules.
- Parameters:
scalars – The scalar to be added.
property_name (str, optional) – The name assign to the scalar property.
- add_scalar_properties_from_file(filename: str, property_name: str = 'y') None [source]
Add scalar properties from a file to the molecules.
- Parameters:
filename (str) – Specify the text file that contains properties.
property_name (str, optional) – The name assign to the scalar property.
- add_xyz_derivative_properties(derivatives, property_name: str = 'y', xyz_derivative_property: str = 'xyz_derivatives') None [source]
Add a XYZ derivative property to the molecule.
- Parameters:
derivatives – The derivatives to be added.
property_name (str, optional) – The name of the associated non-derivative property.
xyz_derivative_property (str, optional) – the name assign to the derivative property.
- add_xyz_derivative_properties_from_file(filename: str, property_name: str = 'y', xyz_derivative_property: str = 'xyz_derivatives') None [source]
Add a XYZ derivatives from a text file to the molecules.
- Parameters:
filename (str) – The filename that contains derivatives to be added.
property_name (str, optional) – The name of the associated non-derivative properties.
xyz_derivative_property (str, optional) – the name assign to the derivative properties.
- add_xyz_vectorial_properties(vectors, xyz_vectorial_property: str = 'xyz_vector') None [source]
Add a XYZ vectorial properties to the molecules.
- Parameters:
vectors – The vectors to be added.
xyz_vectorial_property (str, optional) – the name assign to the vectorial properties.
- add_xyz_vectorial_properties_from_file(filename: str, xyz_vectorial_property: str = 'xyz_vector') None [source]
Add a XYZ derivatives from a text file to the molecules.
- Parameters:
filename (str) – The filename that contains vectorial properties to be added.
xyz_vectorial_property (str, optional) – the name assign to the vectorial properties.
- write_file_with_xyz_coordinates(filename: str) None [source]
Write the molecular geometries into a file in XYZ format.
- Parameters:
filename (str) – The name of the file to be written.
- write_file_with_properties(filename, property_to_write='y')[source]
Write a property of molecules to a text file.
- property atomic_numbers: ndarray
The 2D array of the atomic numbers of each atom, for all molecules in the database.
- property element_symbols: ndarray
The 2D array of the element symbols of each atom, for all molecules in the database.
- property ids
The IDs of the molecules in the database.
- property smiles: str
The SMILES string of the molecules in the database.
- write_file_with_smiles(filename)[source]
Write the SMILES of the molecules in the database to a file.
- property nuclear_masses
The nuclear_masses of the molecules in the database.
- property charges
The electric charges of the molecules in the database.
- property multiplicities
The multiplicities of the molecules in the database.
- get_properties(property_name='y')[source]
Return the properties of the molecules by a given property name.
- set_properties(**kwargs)[source]
Set properties of the molecules by given property name(s) as keyword(s).
- get_xyz_derivative_properties(xyz_derivative_property='xyz_derivatives')[source]
Return XYZ derivative properties by the name.
- write_file_with_xyz_derivative_properties(filename, xyz_derivative_property_to_write='xyz_derivatives')[source]
Write XYZ derivative properties into a file.
- write_file_with_xyz_vectorial_properties(filename, xyz_vectorial_property_to_write='xyz_vector')[source]
Write XYZ vectorial properties into a file.
- write_file_with_hessian(filename, hessian_property_to_write='hessian')[source]
Write Hessians into a file.
- copy(atomic_labels=None, molecular_labels=None, molecular_database_labels=None)[source]
Return a copy of the database.
- property xyz_coordinates
The XYZ coordinates of each atom in every molecule.
- class mlatom.data.molecular_trajectory(steps=None)[source]
A class for storing/access molecular trajectory data, which is generated from a dynamics or a optimization task.
- dump(filename=None, format=None)[source]
Dump the molecular_trajectory object into a file.
Available formats are:
'h5md'
(requires python moduleh5py
andpyh5md
)'json'
'plain_text'
- class mlatom.data.h5md(filename: str, data: Dict[str, Any] = {}, mode: str = 'w')[source]
Saving trajectory data to file in H5MD format
- Parameters:
filename (str) – The filename of the h5md file output.
data (Dict) – The data to be stored (optional, if provided, the file will be closed after storing data).
mode (str, optional) – A string that controls the file processing mode (default value: ‘w’ for a new file, ‘r+’ for an exisiting file). The choices are listed in the table below which is consistent with
pyh5md.File()
r
Readonly, file must exist
r+
Read/write, file must exist
w
Create file, truncate if exists
w- or x
Create file, fail if exists
Examples:
traj0 = h5md('traj.h5') # open 'traj.h5' traj1 = h5md('/tmp/test.h5', mode='r') # open an existing file in readonly mode traj2 = h5md('/tmp/traj2.h5', data={'time': 1.0, 'total_energy': -32.1, 'test': 8848}) # add some data to the file, then close the file traj0.write(data) # write data to opened file traj0(data) # an alternative way to write data data = traj0.export() # export the data in the opened file data = traj0() # an alternative way to export data with h5md('test.h5') as traj: # export with a with statement data = traj.export() traj0.close() # close the file
Note
the default data path in HDF5 file
- particles/all:
‘box’, ‘gradients’, ‘mass’, ‘nad’, ‘names’, ‘position’, ‘species’, ‘velocities’
- observables:
‘angular_momentum’, ‘generated_random_number’, ‘kinetic_energy’, ‘linear_momentum’, ‘nstatdyn’, ‘oscillator_strengths’, ‘populations’, ‘potential_energy’, ‘random_seed’, ‘sh_probabilities’, ‘total_energy’, ‘wavefunctions’,
and any other keywords
- h5
the HDF5 file object
- write(data: Dict[str, Any]) None [source]
Write data to the opened H5 file. Data should be a dictionary-like object with ‘time’ in its keys().
- export() Dict[str, ndarray] [source]
Export the data in the opened H5 file.
- Returns:
A dictionary of the trajectory data in the H5 file.
- __call__() Dict[str, ndarray]
Export the data in the opened H5 file.
- Returns:
A dictionary of the trajectory data in the H5 file.
Models
methods
!---------------------------------------------------------------------------!
! models: Module with models !
! Implementations by: Pavlo O. Dral !
!---------------------------------------------------------------------------!
- class mlatom.models.methods(method: str | None = None, program: str | None = None, **kwargs)[source]
Create a model object with a specified method.
- Parameters:
method (str) – Specify the method. Available methods are listed in the section below.
program (str, optional) – Specify the program to use.
**kwargs – Other method-specific options
Available Methods:
'AIQM1'
,'AIQM1@DFT'
,'AIQM1@DFT*'
,'AM1'
,'ANI-1ccx'
,'ANI-1x'
,'ANI-1x-D4'
,'ANI-2x'
,'ANI-2x-D4'
,'CCSD(T)*/CBS'
,'CNDO/2'
,'D4'
,'DFTB0'
,'DFTB2'
,'DFTB3'
,'GFN2-xTB'
,'MINDO/3'
,'MNDO'
,'MNDO/H'
,'MNDO/d'
,'MNDO/dH'
,'MNDOC'
,'ODM2'
,'ODM2*'
,'ODM3'
,'ODM3*'
,'OM1'
,'OM2'
,'OM3'
,'PM3'
,'PM6'
,'RM1'
,'SCC-DFTB'
,'SCC-DFTB-heats'
.Methods listed above can be accepted without specifying a program.
And other methods supported by supported programs (e.g.:
'gaussian'
,''xtb''
,'pyscf'
), can also be accepted with a program specifed.- property nthreads
int([x]) -> integer int(x, base=10) -> integer
Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating point numbers, this truncates towards zero.
If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4
- predict(molecular_database=None, molecule=None, calculate_energy=True, calculate_energy_gradients=False, calculate_hessian=False)[source]
Make predictions for molecular geometries with the model.
- Parameters:
molecular_database (
mlatom.data.molecular_database
, optional) – A database contains the molecules whose properties need to be predicted by the model.molecule (
mlatom.models.molecule
, optional) – A molecule object whose property needs to be predicted by the model.calculate_energy (bool, optional) – Use the model to calculate energy.
calculate_energy_gradients (bool, optional) – Use the model to calculate energy gradients.
calculate_hessian (bool, optional) – Use the model to calculate energy hessian.
AIQM1
!---------------------------------------------------------------------------!
! aiqm1: Artificial intelligence quantum-mechanical method 1 !
! Implementations by: Peikung Zheng & Pavlo O. Dral !
!---------------------------------------------------------------------------!
- class mlatom.aiqm1.aiqm1(method='AIQM1', qm_program=None, qm_program_kwargs={}, dftd4_kwargs={}, **kwargs)[source]
The Artificial intelligence–quantum mechanical method as in the AIQM1 paper.
- Parameters:
method (str, optional) – AIQM method used. Currently supports AIQM1, AIQM1@DFT*, and AIQM1@DFT. Default value: AIQM1.
qm_program (str) – The QM program used in the calculation of ODM2* part. Currently supports MNDO and Sparrow program.
qm_program_kwargs (dictionary, optional) – Keywords passed to QM program.
# Initialize molecule mol = ml.data.molecule() mol.read_from_xyz_file(filename='ethanol.xyz') # Run AIQM1 calculation aiqm1 = ml.models.methods(method='AIQM1', qm_program='MNDO') aiqm1.predict(molecule=mol, calculate_energy=True, calculate_energy_gradients=True) # Get energy, gradient, and prediction uncertainty of AIQM1 energy = mol.energy gradient = mol.gradient std = mol.aiqm1_nn.energy_standard_deviation
- predict(molecular_database=None, molecule=None, calculate_energy=True, calculate_energy_gradients=False, calculate_hessian=False)[source]
Make predictions for molecular geometries with the model.
- Parameters:
molecular_database (
mlatom.data.molecular_database
, optional) – A database contains the molecules whose properties need to be predicted by the model.molecule (
mlatom.models.molecule
, optional) – A molecule object whose property needs to be predicted by the model.calculate_energy (bool, optional) – Use the model to calculate energy.
calculate_energy_gradients (bool, optional) – Use the model to calculate energy gradients.
calculate_hessian (bool, optional) – Use the model to calculate energy hessian.
ml_model
!---------------------------------------------------------------------------!
! models: Module with models !
! Implementations by: Pavlo O. Dral !
!---------------------------------------------------------------------------!
- mlatom.models.ani(**kwargs)[source]
Returns an ANI model object (see
mlatom.interfaces.torchani_interface.ani
).
- mlatom.models.dpmd(**kwargs)[source]
Returns an DPMD model object (see
mlatom.interfaces.dpmd_interface.dpmd
).
- mlatom.models.gap(**kwargs)[source]
Returns an GAP model object (see
mlatom.interfaces.gap_interface.gap
).
- mlatom.models.physnet(**kwargs)[source]
Returns an PhysNet model object (see
mlatom.interfaces.physnet_interface.physnet
).
- mlatom.models.sgdml(**kwargs)[source]
Returns an sGDML model object (see
mlatom.interfaces.sgdml_interface.sgdml
).
model_tree_node
!---------------------------------------------------------------------------!
! models: Module with models !
! Implementations by: Pavlo O. Dral !
!---------------------------------------------------------------------------!
- class mlatom.models.model_tree_node(name=None, parent=None, children=None, operator=None, model=None)[source]
Create a model tree node.
- Parameters:
name (str) – The name assign to the object.
parent – The parent of the model node.
children – The children of this model tree node.
operator – Specify the operation to be made when making predictions.
- predict(**kwargs)[source]
Make predictions for molecular geometries with the model.
- Parameters:
molecular_database (
mlatom.data.molecular_database
, optional) – A database contains the molecules whose properties need to be predicted by the model.molecule (
mlatom.models.molecule
, optional) – A molecule object whose property needs to be predicted by the model.calculate_energy (bool, optional) – Use the model to calculate energy.
calculate_energy_gradients (bool, optional) – Use the model to calculate energy gradients.
calculate_hessian (bool, optional) – Use the model to calculate energy hessian.
Interfaces
Interfaces to third-party software.
TorchANI
!---------------------------------------------------------------------------!
! Interface_TorchANI: Interface between TorchANI and MLatom !
! Implementations by: Fuchun Ge and Max Pinheiro Jr !
!---------------------------------------------------------------------------!
- class mlatom.interfaces.torchani_interface.ani(model_file: str | None = None, device: str | None = None, hyperparameters: Dict[str, Any] | hyperparameters = {}, verbose=1)[source]
Create an ANI (ANAKIN-ME: Accurate NeurAl networK engINe for Molecular Energie) model object.
Interfaces to TorchANI.
- Parameters:
model_file (str, optional) – The filename that the model to be saved with or loaded from.
device (str, optional) – Indicate which device the calculation will be run on. i.e. ‘cpu’ for CPU, ‘cuda’ for Nvidia GPUs. When not speficied, it will try to use CUDA if there exists valid
CUDA_VISIBLE_DEVICES
in the environ of system.hyperparameters (Dict[str, Any] |
mlatom.models.hyperparameters
, optional) – Updates the hyperparameters of the model with provided.verbose (int, optional) – 0 for silence, 1 for verbosity.
- save(model_file: str = '') None [source]
Save the model to file (.pt format).
- Parameters:
model_file (str, optional) – The filename that the model to be saved into. If not provided, a randomly generated string will be used.
- load(model_file: str = '', species_order: List[str] | None = None, AEV_parameters: Dict | None = None, self_energies: List[float] | None = None, reset_parameters: bool = False, method: str = '') None [source]
Load a saved ANI model from file (.pt format).
- Parameters:
model_file (str) – The filename of the model to be loaded.
species_order (List[str], optional) – Manually provide species order if it’s not present in the saved model.
AEV_parameters (Dict, optional) – Manually provide AEV parameters if it’s not present in the saved model.
self_energies (List[float], optional) – Manually provide self energies if it’s not present in the saved model.
reset_parameters (bool) – Reset network paramters in the loaded model.
method (str) – Load an ANI method, see also
ani.load_ani_model()
.
- load_ani_model(method: str, **hyperparameters) None [source]
Load an ANI model.
- Arguments:
method(str): Can be
'ANI-1x'
,'ANI-1ccx'
, or'ANI-2x'
.
- train(molecular_database: data.molecular_database, property_to_learn: str = 'energy', xyz_derivative_property_to_learn: str = None, validation_molecular_database: data.molecular_database | str | None = 'sample_from_molecular_database', hyperparameters: Dict[str, Any] | models.hyperparameters = {}, spliting_ratio: float = 0.8, save_model: bool = True, check_point: str = None, reset_optim_state: bool = False, use_last_model: bool = False, reset_parameters: bool = False, reset_network: bool = False, reset_optimizer: bool = False, save_every_epoch: bool = False) None [source]
Train the model with molecular database provided.
- Parameters:
molecular_database (
mlatom.data.molecular_database
) – The database of molecules for training.property_to_learn (str, optional) – The label of property to be learned in model training.
xyz_derivative_property_to_learn (str, optional) – The label of XYZ derivative property to be learned.
validation_molecular_database (
mlatom.data.molecular_database
| str, optional) – Explicitly defines the database for validation, or use'sample_from_molecular_database'
to make it sampled from the training set.hyperparameters (Dict[str, Any] |
mlatom.models.hyperparameters
, optional) – Updates the hyperparameters of the model with provided.spliting_ratio (float, optional) – The ratio sub-training dataset in the whole training dataset.
save_model (bool, optional) – Whether save the model to disk during training process. Note that the model might be saved many times during training.
reset_optim_state (bool, optional) – Whether to reset the state of optimizer.
use_last_model (bool, optional) – Whether to keep the
self.model
as it is in the last training epoch. IfFalse
, the best model will be loaded to memory at the end of training.reset_parameters (bool, optional) – Whether to reset the model’s parameters before training.
reset_network (bool, optional) – Whether to re-construct the network before training.
reset_optimizer (bool, optional) – Whether to re-define the optimizer before training .
save_every_epoch (bool, optional) – Whether to save model in every epoch, valid when
save_model
isTrue
.
- predict(molecular_database: data.molecular_database = None, molecule: data.molecule = None, calculate_energy: bool = False, calculate_energy_gradients: bool = False, calculate_hessian: bool = False, property_to_predict: str | None = 'estimated_y', xyz_derivative_property_to_predict: str | None = None, hessian_to_predict: str | None = None, batch_size: int = 65536) None [source]
Make predictions for molecular geometries with the model.
- Parameters:
molecular_database (
mlatom.data.molecular_database
, optional) – A database contains the molecules whose properties need to be predicted by the model.molecule (
mlatom.models.molecule
, optional) – A molecule object whose property needs to be predicted by the model.calculate_energy (bool, optional) – Use the model to calculate energy.
calculate_energy_gradients (bool, optional) – Use the model to calculate energy gradients.
calculate_hessian (bool, optional) – Use the model to calculate energy hessian.
property_to_predict (str, optional) – The label name where the predicted properties to be saved.
xyz_derivative_property_to_predict (str, optional) – The label name where the predicted XYZ derivatives to be saved.
hessian_to_predict (str, optional) – The label name where the predicted Hessians to be saved.
batch_size (int, optional) – The batch size for batch-predictions.
- NN_initialize(a: float = 1.0) None [source]
Reset the network parameters using
torch.nn.init.kaiming_normal_()
.- Parameters:
a (float) – Check torch.nn.init.kaiming_normal_().
- fix_layers(layers_to_fix: List[List[int]] | List[int])[source]
Fix specific layers to be non-trainable for each element.
- Parameters:
layers_to_fix (List) –
Should be:
A list of integers. Layers indicate by the integers will be fixed
A list of lists of integers. Each sub-list defines the layers to be fixed for each species, in the order of self.species_order.
- class mlatom.interfaces.torchani_interface.ani_methods(method: str = 'ANI-1ccx', device: str = 'cpu', **kwargs)[source]
Creat a model object with on of the ANI methods
- Parameters:
method (str) – A string that specifies the method. Available choices:
'ANI-1x'
,'ANI-1ccx'
, or'ANI-2x'
.device (str, optional) – Indicate which device the calculation will be run on. i.e. ‘cpu’ for CPU, ‘cuda’ for Nvidia GPUs. When not speficied, it will try to use CUDA if there exists valid
CUDA_VISIBLE_DEVICES
in the environ of system.
- predict(molecular_database: data.molecular_database = None, molecule: data.molecule = None, calculate_energy: bool = False, calculate_energy_gradients: bool = False, calculate_hessian: bool = False, batch_size: int = 65536) None [source]
Make predictions for molecular geometries with the model.
- Parameters:
molecular_database (
mlatom.data.molecular_database
, optional) – A database contains the molecules whose properties need to be predicted by the model.molecule (
mlatom.models.molecule
, optional) – A molecule object whose property needs to be predicted by the model.calculate_energy (bool, optional) – Use the model to calculate energy.
calculate_energy_gradients (bool, optional) – Use the model to calculate energy gradients.
calculate_hessian (bool, optional) – Use the model to calculate energy hessian.
batch_size (int, optional) – The batch size for batch-predictions.
DeepMD-kit
!---------------------------------------------------------------------------!
! Interface_DeePMDkit: Interface between DeePMD-kit and MLatom !
! Implementations by: Fuchun Ge !
!---------------------------------------------------------------------------!
- class mlatom.interfaces.dpmd_interface.dpmd(model_file=None, hyperparameters={}, verbose=1)[source]
Create an DeepPot-SE model object.
Interfaces to DeepMD-kit.
- Parameters:
model_file (str, optional) – The filename that the model to be saved with or loaded from.
hyperparameters (Dict[str, Any] |
mlatom.models.hyperparameters
, optional) – Updates the hyperparameters of the model with provided.verbose (int, optional) – 0 for silence, 1 for verbosity.
- train(molecular_database: molecular_database, property_to_learn: str = 'energy', xyz_derivative_property_to_learn: str | None = None, validation_molecular_database: molecular_database | str | None = 'sample_from_molecular_database', hyperparameters: Dict[str, Any] | hyperparameters = {}, spliting_ratio=0.8, stdout=None, stderr=None, json_input=None, dirname=None)[source]
Train the model with molecular database provided.
- Parameters:
molecular_database (
mlatom.data.molecular_database
) – The database of molecules for training.property_to_learn (str, optional) – The label of property to be learned in model training.
xyz_derivative_property_to_learn (str, optional) – The label of XYZ derivative property to be learned.
- predict(molecular_database: data.molecular_database = None, molecule: data.molecule = None, calculate_energy: bool = False, calculate_energy_gradients: bool = False, calculate_hessian: bool = False, property_to_predict: str | None = 'estimated_y', xyz_derivative_property_to_predict: str | None = None, hessian_to_predict: str | None = None) None [source]
Make predictions for molecular geometries with the model.
- Parameters:
molecular_database (
mlatom.data.molecular_database
, optional) – A database contains the molecules whose properties need to be predicted by the model.molecule (
mlatom.models.molecule
, optional) – A molecule object whose property needs to be predicted by the model.calculate_energy (bool, optional) – Use the model to calculate energy.
calculate_energy_gradients (bool, optional) – Use the model to calculate energy gradients.
calculate_hessian (bool, optional) – Use the model to calculate energy hessian.
property_to_predict (str, optional) – The label name where the predicted properties to be saved.
xyz_derivative_property_to_predict (str, optional) – The label name where the predicted XYZ derivatives to be saved.
hessian_to_predict (str, optional) – The label name where the predicted Hessians to be saved.
GAP/QUIP
!---------------------------------------------------------------------------!
! Interface_GAP: Interface between GAP and MLatom !
! Implementations by: Fuchun Ge !
!---------------------------------------------------------------------------!
- class mlatom.interfaces.gap_interface.gap(model_file=None, hyperparameters={}, verbose=1)[source]
Create an GAP-SOAP model object.
Interfaces to QUIP.
- Parameters:
model_file (str, optional) – The filename that the model to be saved with or loaded from.
hyperparameters (Dict[str, Any] |
mlatom.models.hyperparameters
, optional) – Updates the hyperparameters of the model with provided.verbose (int, optional) – 0 for silence, 1 for verbosity.
- train(molecular_database: molecular_database, property_to_learn: str = 'energy', xyz_derivative_property_to_learn: str | None = None, hyperparameters: Dict[str, Any] | hyperparameters = {}, stdout=None, stderr=None)[source]
Train the model with molecular database provided.
- Parameters:
molecular_database (
mlatom.data.molecular_database
) – The database of molecules for training.property_to_learn (str, optional) – The label of property to be learned in model training.
xyz_derivative_property_to_learn (str, optional) – The label of XYZ derivative property to be learned.
- predict(molecular_database: data.molecular_database = None, molecule: data.molecule = None, calculate_energy: bool = False, calculate_energy_gradients: bool = False, calculate_hessian: bool = False, property_to_predict: str | None = 'estimated_y', xyz_derivative_property_to_predict: str | None = None, hessian_to_predict: str | None = None) None [source]
Make predictions for molecular geometries with the model.
- Parameters:
molecular_database (
mlatom.data.molecular_database
, optional) – A database contains the molecules whose properties need to be predicted by the model.molecule (
mlatom.models.molecule
, optional) – A molecule object whose property needs to be predicted by the model.calculate_energy (bool, optional) – Use the model to calculate energy.
calculate_energy_gradients (bool, optional) – Use the model to calculate energy gradients.
calculate_hessian (bool, optional) – Use the model to calculate energy hessian.
property_to_predict (str, optional) – The label name where the predicted properties to be saved.
xyz_derivative_property_to_predict (str, optional) – The label name where the predicted XYZ derivatives to be saved.
hessian_to_predict (str, optional) – The label name where the predicted Hessians to be saved.
PhysNet
!---------------------------------------------------------------------------!
! Interface_PhysNet: Interface between PhysNet and MLatom !
! Implementations by: Fuchun Ge and Max Pinheiro Jr !
!---------------------------------------------------------------------------!
- class mlatom.interfaces.physnet_interface.physnet(model_file=None, hyperparameters={}, verbose=1)[source]
Create an PhysNet model object.
Interfaces to PhysNet program.
- Parameters:
model_file (str, optional) – The filename that the model to be saved with or loaded from.
hyperparameters (Dict[str, Any] |
mlatom.models.hyperparameters
, optional) – Updates the hyperparameters of the model with provided.verbose (int, optional) – 0 for silence, 1 for verbosity.
- train(molecular_database: molecular_database, property_to_learn: str = 'energy', xyz_derivative_property_to_learn: str | None = None, validation_molecular_database: molecular_database | str | None = 'sample_from_molecular_database', hyperparameters: Dict[str, Any] | hyperparameters = {}, spliting_ratio=0.8, save_model=True, log=True, check_point=False, use_last_model=False, summary_interval=1, validation_interval=1, save_interval=1, record_run_metadata=0) None [source]
Train the model with molecular database provided.
- Parameters:
molecular_database (
mlatom.data.molecular_database
) – The database of molecules for training.property_to_learn (str, optional) – The label of property to be learned in model training.
xyz_derivative_property_to_learn (str, optional) – The label of XYZ derivative property to be learned.
- predict(molecular_database: data.molecular_database = None, molecule: data.molecule = None, calculate_energy: bool = False, calculate_energy_gradients: bool = False, calculate_hessian: bool = False, property_to_predict: str | None = 'estimated_y', xyz_derivative_property_to_predict: str | None = None, hessian_to_predict: str | None = None) None [source]
Make predictions for molecular geometries with the model.
- Parameters:
molecular_database (
mlatom.data.molecular_database
, optional) – A database contains the molecules whose properties need to be predicted by the model.molecule (
mlatom.models.molecule
, optional) – A molecule object whose property needs to be predicted by the model.calculate_energy (bool, optional) – Use the model to calculate energy.
calculate_energy_gradients (bool, optional) – Use the model to calculate energy gradients.
calculate_hessian (bool, optional) – Use the model to calculate energy hessian.
property_to_predict (str, optional) – The label name where the predicted properties to be saved.
xyz_derivative_property_to_predict (str, optional) – The label name where the predicted XYZ derivatives to be saved.
hessian_to_predict (str, optional) – The label name where the predicted Hessians to be saved.
sGDML
!---------------------------------------------------------------------------!
! Interface_sGDML: Interface between sGDML and MLatom !
! Implementations by: Fuchun Ge !
!---------------------------------------------------------------------------!
- class mlatom.interfaces.sgdml_interface.sgdml(model_file=None, hyperparameters={}, verbose=1, max_memory=None, max_processes=None, use_torch=False, lazy_training=False)[source]
Create an sGDML model object.
Interfaces to sGDML.
- Parameters:
model_file (str, optional) – The filename that the model to be saved with or loaded from.
hyperparameters (Dict[str, Any] |
mlatom.models.hyperparameters
, optional) – Updates the hyperparameters of the model with provided.verbose (int, optional) – 0 for silence, 1 for verbosity.
Hyperparameters:
Please refer to the sgdml manual
no_E: mlatom.models.hyperparameter(value=False) gdml: mlatom.models.hyperparameter(value=False) perms: mlatom.models.hyperparameter(value=None) sigma: mlatom.models.hyperparameter(value=None) E_cstr: mlatom.models.hyperparameter(value=False) cprsn: mlatom.models.hyperparameter(value=False)
- train(molecular_database: molecular_database, property_to_learn: str = 'energy', xyz_derivative_property_to_learn: str | None = None, validation_molecular_database: molecular_database | str | None = None, hyperparameters: Dict[str, Any] | hyperparameters = {}, spliting_ratio=0.8, save_model=True, task_dir=None, overwrite=False, max_memory=None, max_processes=None, use_torch=None, lazy_training=None)[source]
Train the model with molecular database provided.
- Parameters:
molecular_database (
mlatom.data.molecular_database
) – The database of molecules for training.property_to_learn (str, optional) – The label of property to be learned in model training.
xyz_derivative_property_to_learn (str, optional) – The label of XYZ derivative property to be learned.
- predict(molecular_database: data.molecular_database = None, molecule: data.molecule = None, calculate_energy: bool = False, calculate_energy_gradients: bool = False, calculate_hessian: bool = False, property_to_predict: str | None = 'estimated_y', xyz_derivative_property_to_predict: str | None = None, hessian_to_predict: str | None = None, batch_size: int = 65536) None [source]
Make predictions for molecular geometries with the model.
- Parameters:
molecular_database (
mlatom.data.molecular_database
, optional) – A database contains the molecules whose properties need to be predicted by the model.molecule (
mlatom.models.molecule
, optional) – A molecule object whose property needs to be predicted by the model.calculate_energy (bool, optional) – Use the model to calculate energy.
calculate_energy_gradients (bool, optional) – Use the model to calculate energy gradients.
calculate_hessian (bool, optional) – Use the model to calculate energy hessian.
property_to_predict (str, optional) – The label name where the predicted properties to be saved.
xyz_derivative_property_to_predict (str, optional) – The label name where the predicted XYZ derivatives to be saved.
hessian_to_predict (str, optional) – The label name where the predicted Hessians to be saved.
batch_size (int, optional) – The batch size for batch-predictions.
Gaussian
!---------------------------------------------------------------------------!
! gaussian: interface to the Gaussian program !
! Implementations by: Pavlo O. Dral, Peikun Zheng, Yi-Fan Hou !
!---------------------------------------------------------------------------!
- class mlatom.interfaces.gaussian_interface.gaussian_methods(method='B3LYP/6-31G*', nthreads=1, save_files_in_current_directory=False, **kwargs)[source]
Gaussian interface
- Parameters:
method (str) – Method to use
nthreads (int) – equivalent to %proc in Gaussian input file
save_files_in_current_directory (bool) – save input and output files or not
Note
The format of method should be the same as that in Gaussian, e.g.,
'B3LYP/6-31G*'
- predict(molecular_database=None, molecule=None, calculate_energy=True, calculate_energy_gradients=False, calculate_hessian=False, gaussian_keywords=None)[source]
Make predictions for molecular geometries with the model.
- Parameters:
molecular_database (
mlatom.data.molecular_database
, optional) – A database contains the molecules whose properties need to be predicted by the model.molecule (
mlatom.models.molecule
, optional) – A molecule object whose property needs to be predicted by the model.calculate_energy (bool, optional) – Use the model to calculate energy.
calculate_energy_gradients (bool, optional) – Use the model to calculate energy gradients.
calculate_hessian (bool, optional) – Use the model to calculate energy hessian.
gaussian_keywords (some type) –
# needs to be documented
.
DFT-D4
!---------------------------------------------------------------------------!
! dftd4: interface to the dftd4 program !
! Implementations by: Pavlo O. Dral & Peikun Zheng !
!---------------------------------------------------------------------------!
- class mlatom.interfaces.dftd4_interface.dftd4_methods(functional=None, save_files_in_current_directory=True, **kwargs)[source]
DFT-D4 interface
- Parameters:
functional (str) – functional to use
Note
The default DFT-D4 implementation provides a shared memory parallelisation for CPUs. They offer openMP parallelisation, which is not implemented here currently. For more discussion, please refer to https://github.com/dftd4/dftd4/issues/20.
- predict(molecular_database=None, molecule=None, calculate_energy=True, calculate_energy_gradients=False, calculate_hessian=False)[source]
Make predictions for molecular geometries with the model.
- Parameters:
molecular_database (
mlatom.data.molecular_database
, optional) – A database contains the molecules whose properties need to be predicted by the model.molecule (
mlatom.models.molecule
, optional) – A molecule object whose property needs to be predicted by the model.calculate_energy (bool, optional) – Use the model to calculate energy.
calculate_energy_gradients (bool, optional) – Use the model to calculate energy gradients.
calculate_hessian (bool, optional) – Use the model to calculate energy hessian.
PySCF
!---------------------------------------------------------------------------!
! Interface_PySCF: interface to the PySCF program !
! Implementations by: Yuxinxin Chen !
!---------------------------------------------------------------------------!
- class mlatom.interfaces.pyscf_interface.pyscf_methods(method='B3LYP/6-31g', **kwargs)[source]
PySCF interface
- Parameters:
method (str) – Method to use
nthreads (int) – Set the number of OMP threads
Note
Methods supported:
Energy: HF, MP2, DFT, CISD, FCI, CCSD/CCSD(T), TD-DFT/TD-HF
Gradients: HF, MP2, DFT, CISD, CCSD, RCCSD(T), TD-DFT/TD-HF
Hessian: HF, DFT
- predict(molecule=None, molecular_database=None, calculate_energy=True, calculate_energy_gradients=False, calculate_hessian=False, **kwargs)[source]
Make predictions for molecular geometries with the model.
- Parameters:
molecular_database (
mlatom.data.molecular_database
, optional) – A database contains the molecules whose properties need to be predicted by the model.molecule (
mlatom.models.molecule
, optional) – A molecule object whose property needs to be predicted by the model.calculate_energy (bool, optional) – Use the model to calculate energy.
calculate_energy_gradients (bool, optional) – Use the model to calculate energy gradients.
calculate_hessian (bool, optional) – Use the model to calculate energy hessian.
**kwargs –
# needs to be documented
.
Sparrow
!---------------------------------------------------------------------------!
! sparrow: interface to the Sparrow program !
! Implementations by: Pavlo O. Dral & Peikun Zheng !
!---------------------------------------------------------------------------!
- class mlatom.interfaces.sparrow_interface.sparrow_methods(method='ODM2*', read_keywords_from_file='', save_files_in_current_directory=False, **kwargs)[source]
Sparrow interface
- Parameters:
method (str) – method to use
Note
Methods supported:
Energy: DFTB0, DFTB2, DFTB3 MNDO, MNDO/d, AM1, PM3, PM6 OM2, OM3, ODM2*, ODM3* AIQM1
Gradients: DFTB0, DFTB2, DFTB3 MNDO, MNDO/d, AM1, PM3, PM6
- predict(molecular_database=None, molecule=None, calculate_energy=True, calculate_energy_gradients=False, calculate_hessian=False)[source]
Make predictions for molecular geometries with the model.
- Parameters:
molecular_database (
mlatom.data.molecular_database
, optional) – A database contains the molecules whose properties need to be predicted by the model.molecule (
mlatom.models.molecule
, optional) – A molecule object whose property needs to be predicted by the model.calculate_energy (bool, optional) – Use the model to calculate energy.
calculate_energy_gradients (bool, optional) – Use the model to calculate energy gradients.
calculate_hessian (bool, optional) – Use the model to calculate energy hessian.
xTB
!---------------------------------------------------------------------------!
! xtb: interface to the xtb program !
! Implementations by: Pavlo O. Dral !
!---------------------------------------------------------------------------!
- class mlatom.interfaces.xtb_interface.xtb_methods(method='GFN2-xTB', read_keywords_from_file='', **kwargs)[source]
xTB interface
- Parameters:
method (str) – xTB methods
read_keywords_from_file (str) – keywords used in xTB
Note
Only GFN2-xTB is available.
Examples:
from ml.interfaces.xtb import xtb_methods() # read molecule from xyz file mol = ml.data.molecule() mol.read_from_xyz_file('sp.xyz') # initialize xtb methods model = xtb_methods(method='GFN2-xTB) # calculate energy, gradients and hessian model.predict(molecule=mol, calculate_energy_gradients=True, calculate_hessian=True) print(mol.energy)
- predict(molecular_database=None, molecule=None, calculate_energy=True, calculate_energy_gradients=False, calculate_hessian=False)[source]
Make predictions for molecular geometries with the model.
- Parameters:
molecular_database (
mlatom.data.molecular_database
, optional) – A database contains the molecules whose properties need to be predicted by the model.molecule (
mlatom.models.molecule
, optional) – A molecule object whose property needs to be predicted by the model.calculate_energy (bool, optional) – Use the model to calculate energy.
calculate_energy_gradients (bool, optional) – Use the model to calculate energy gradients.
calculate_hessian (bool, optional) – Use the model to calculate energy hessian.
MNDO
!---------------------------------------------------------------------------!
! mndo: interface to the MNDO program !
! Implementations by: Pavlo O. Dral & Peikun Zheng !
!---------------------------------------------------------------------------!
- class mlatom.interfaces.mndo_interface.mndo_methods(method='ODM2*', read_keywords_from_file='', save_files_in_current_directory=True, **kwargs)[source]
MNDO interface
- Parameters:
method (str) – method used in MNDO
read_keywords_from_file (str) – keywords used in MNDO
save_files_in_current_directory (bool) – whether to keep input and output file, default True
- predict(molecular_database=None, molecule=None, calculate_energy=True, calculate_energy_gradients=False, calculate_hessian=False)[source]
Make predictions for molecular geometries with the model.
- Parameters:
molecular_database (
mlatom.data.molecular_database
, optional) – A database contains the molecules whose properties need to be predicted by the model.molecule (
mlatom.models.molecule
, optional) – A molecule object whose property needs to be predicted by the model.calculate_energy (bool, optional) – Use the model to calculate energy.
calculate_energy_gradients (bool, optional) – Use the model to calculate energy gradients.
calculate_hessian (bool, optional) – Use the model to calculate energy hessian.
Simulations
!---------------------------------------------------------------------------!
! simulations: Module for simulations !
! Implementations by: Pavlo O. Dral !
!---------------------------------------------------------------------------!
- class mlatom.simulations.optimize_geometry(model=None, initial_molecule=None, molecule=None, ts=False, program=None, optimization_algorithm=None, maximum_number_of_steps=None, convergence_criterion_for_forces=None, working_directory=None)[source]
Geometry optimization.
- Parameters:
model (
mlatom.models.model
ormlatom.models.methods
) – Any model or method which provides energies and forces.initial_molecule (
mlatom.data.molecule
) – The molecule object to relax.ts (bool, optional) – Whether to do transition state search. Currently only be done with program=Gaussian or ASE.
program (str, optional) – The engine used in geomtry optimization. Currently support Gaussian, ASE, and scipy.
optimization_algorithm (str, optional) – The optimization algorithm used in ASE. Default value: LBFGS (ts=False), dimer (ts=False).
maximum_number_of_steps (int, optional) – The maximum steps. Default value: 200.
convergence_criterion_for_forces (float, optional) – Forces convergence criterion in ASE. Default value: 0.02 eV/Angstroms.
working_directory (str, optional) – Working directory. Default value: ‘.’, i.e., current directory.
Examples:
# Initialize molecule mol = ml.data.molecule() mol.read_from_xyz_file(filename='ethanol.xyz') # Initialize methods aiqm1 = ml.models.methods(method='AIQM1', qm_program='MNDO') # Run geometry optimization geomopt = ml.simulations.optimize_geometry(model = aiqm1, initial_molecule=mol, program = 'ASE') # Get the optimized geometry, energy, and gradient optmol = geomopt.optimized_molecule geo = optmol.get_xyz_coordinates() energy = optmol.energy gradient = optmol.get_energy_gradients()
- class mlatom.simulations.freq(model=None, molecule=None, program=None, normal_mode_normalization='mass deweighted unnormalized', anharmonic=False, anharmonic_kwargs={}, working_directory=None)[source]
Frequence analysis.
- Parameters:
model (
mlatom.models.model
ormlatom.models.methods
) – Any model or method which provides energies and forces and Hessian.molecule (
mlatom.data.molecule
) – The molecule object with necessary information.program (str, optional) – The engine used in frequence analysis through modified TorchANI (if Gaussian not found or any other string is given), pyscf or Gaussian interfaces.
normal_mode_normalization (str, optional) – Normal modes output scheme. It should be one of: mass weighted normalized, mass deweighted unnormalized, and mass deweighted unnormalized (default).
anharmonic (bool) – Whether to do anharmonic frequence calculation.
working_directory (str, optional) – Working directory. Default value: ‘.’, i.e., current directory.
Examples:
# Initialize molecule mol = ml.data.molecule() mol.read_from_xyz_file(filename='ethanol.xyz') # Initialize methods aiqm1 = ml.models.methods(method='AIQM1', qm_program='MNDO') # Run frequence analysis ml.simulations.freq(model=aiqm1, molecule=mol, program='ASE') # Get frequencies frequencies = mol.frequencies
- class mlatom.simulations.thermochemistry(model=None, molecule=None, program=None, normal_mode_normalization='mass deweighted unnormalized')[source]
Thermochemical properties calculation.
- Parameters:
model (
mlatom.models.model
ormlatom.models.methods
) – Any model or method which provides energies and forces and Hessian.molecule (
mlatom.data.molecule
) – The molecule object with necessary information.program (str) – The engine used in thermochemical properties calculation. Currently support Gaussian and ASE.
normal_mode_normalization (str, optional) – Normal modes output scheme. It should be one of: mass weighted normalized, mass deweighted unnormalized, and mass deweighted unnormalized (default).
# Initialize molecule mol = ml.data.molecule() mol.read_from_xyz_file(filename='ethanol.xyz') # Initialize methods aiqm1 = ml.models.methods(method='AIQM1', qm_program='MNDO') # Run thermochemical properties calculation ml.simulations.thermochemistry(model=aiqm1, molecule=mol, program='ASE') # Get ZPE and heat of formation ZPE = mol.ZPE Hof = mol.DeltaHf298
MD
!---------------------------------------------------------------------------!
! MD: Module for molecular dynamics !
! Implementations by: Yi-Fan Hou & Pavlo O. Dral !
!---------------------------------------------------------------------------!
- class mlatom.md.md(model=None, molecule_with_initial_conditions=None, molecule=None, ensemble='NVE', thermostat=None, time_step=0.1, maximum_propagation_time=1000, dump_trajectory_interval=None, filename=None, format='h5md', stop_function=None, stop_function_kwargs=None)[source]
MD object
Initialize and propagate MD
- Parameters:
model (
mlatom.models.model
ormlatom.models.methods
) – Any model or method which provides energies and forces.molecule_with_initial_conditions (
data.molecule
) – The molecule with initial conditions.ensemble (str, optional) – Which kind of ensemble to use.
thermostat (
thermostat.Thermostat
) – The thermostat applied to the system.time_step (float) – Time step in femtoseconds.
maximum_propagation_time (float) – Maximum propagation time in femtoseconds.
dump_trajectory_interval (int, optional) – Dump trajectory at which interval. Set to
None
to disable dumping.filename (str, optional) – The file that saves the dumped trajectory
format (str, optional) – Format in which the dumped trajectory is saved
stop_function (any, optional) – User-defined function that stops MD before
maximum_propagation_time
stop_function_kwargs (Dict, optional) – Kwargs of
stop_function
ensemble
description
'NVE'
(default)Microcanonical (NVE) ensemble
'NVT'
Canonical (NVT) ensemble
thermostat
description
ml.md.Andersen_thermostat
Andersen thermostat
ml.md.Nose_Hoover_thermostat
Hose-Hoover thermostat
None
(default)No thermostat is applied
Examples:
# Initialize molecule mol = ml.data.molecule() mol.read_from_xyz_file(filename='ethanol.xyz') # Initialize methods aiqm1 = ml.models.methods(method='AIQM1') # User-defined initial condition init_cond_db = ml.generate_initial_conditions(molecule = mol, generation_method = 'user-defined', file_with_initial_xyz_coordinates = 'ethanol.xyz', file_with_initial_xyz_velocities = 'ethanol.vxyz') init_mol = init_cond_db.molecules[0] # Initialize thermostat nose_hoover = ml.md.Nose_Hoover_thermostat(temperature=300,molecule=init_mol,degrees_of_freedom=-6) # Run dynamics dyn = ml.md(model=aiqm1, molecule_with_initial_conditions = init_mol, ensemble='NVT', thermostat=nose_hoover, time_step=0.5, maximum_propagation_time = 10.0) # Dump trajectory traj = dyn.molecular_trajectory traj.dump(filename='traj', format='plain_text') traj.dump(filename='traj.h5', format='h5md')
Note
Trajectory is saved in
ml.md.molecular_trajectory
, which is aml.data.molecular_trajectory
classWarning
In MLatom, energy unit is Hartree and distance unit is Angstrom. Make sure that the units in your model are consistent.
- class Andersen_thermostat(**kwargs)
Andersen thermostat object
- Parameters:
gamma (float) – collision rate in fs^{-1}, 0.2 by default
temperature (float) – System temperature to equilibrate in Kelvin, 300 by default
- class Nose_Hoover_thermostat(**kwargs)
Nose-Hoover thermostat object
- Parameters:
nose_hoover_chain_length (int) – Nose Hoover chain length, should be a positive number, 3 by default
multiple_time_step (int) – Multiple time step, should be a positive number, 3 by default
number_of_yoshida_suzuki_steps (int) – Number of Yoshida Suzuki steps, can be any in (1,3,5,7), 7 by default
nose_hoover_chain_frequency (float) – Nose-Hoover chain frequency in $fs^{-1}$, 0.0625 by default, should be comparable to the frequency you want to equilibrate
temperature (float) – System temperature to equilibrate in Kelvin, 300 by default
molecule (
data.molecule
) – The molecule to be equilibrateddegrees_of_freedom – Degrees of freedom of the system
initial_conditions
!---------------------------------------------------------------------------!
! initial_conditions: Module for generating initial conditions !
! Implementations by: Yi-Fan Hou & Pavlo O. Dral !
!---------------------------------------------------------------------------!
- mlatom.initial_conditions.generate_initial_conditions(molecule=None, generation_method=None, number_of_initial_conditions=1, file_with_initial_xyz_coordinates=None, file_with_initial_xyz_velocities=None, eliminate_angular_momentum=True, degrees_of_freedom=None, initial_temperature=None, initial_kinetic_energy=None)[source]
Generate initial conditions
- Parameters:
molecule (
data.molecule
) – Molecule with necessary informationgeneration_method (str) – Initial condition generation method
number_of_initial_conditions (int) – Number of initial conditions to generate, 1 by default
file_with_initial_xyz_coordinates (str) – File with initial xyz coordinates, only valid for
generation_method='user-defined'
file_with_initial_xyz_velocities (str) – File with initial xyz velocities, only valid for
generation_method='user-defined'
eliminate_angular_momentum (bool) – Remove angular momentum from velocities, valid for
generation_method='random'
degrees_of_freedom (int) – Degrees of freedom of the molecule, by default remove translational and rotational degrees of freedom. It can be a negative value, which means that some value is subtracted from 3*Natoms
initial_temperature (float) – Initial temperature in Kelvin, control random initial velocities
initial_kinetic_energy (float) – Initial temperature in Hartree, control random initial velocities
generation_method
description
'user-defined'
(default)Use user-defined initial conditions
'random'
Generate random velocities
- Returns:
A molecular database (
ml.data.molecular_database
) withnumber_of_initial_conditions
initial conditions
Examples:
# Use user-defined initial conditions init_cond_db = ml.generate_initial_conditions(molecule = mol, generation_method = 'user-defined', file_with_initial_xyz_coordinates = 'ethanol.xyz', file_with_initial_xyz_velocities = 'ethanol.vxyz', number_of_initial_conditions = 1) # Generate random velocities init_cond_db = ml.generate_initial_conditions(molecule = mol, generation_method = 'random', initial_temperature = 300, number_of_initial_conditions = 1)