Manual
Please consult with Features for an overview of MLatom capabilities. This page provides details on how to use MLatom for various types of calculations.
Table of Contents
Installation
First download the package or run python3 m pip install MLatom
.
In the downloaded package, a Python wrapper MLatom.py together with other Python 3.6+ scripts and a statically compiled binary of MLatomF for Linux systems are provided. These files can be saved in any directory and used directly without any modifications to the environment variables etc. You may need to make files executable by using command line option chmod +x MLatom.py MLatomF
. And add your MLatom path into the $PATH
variable with the command: export PATH=$PATH:/path/to/MLatom
(it’s advisable to write it into .bashrc
file)
Requirements for MLNEA
To run MLNEA calculations of absorption cross sections, you also need to define some environment:
 Install NewtonX (NX)
 use
export NX=/path/to/NewtonX
to define the$NX
 install matplotlib with the command
python3 m pip install matplotlib
 Have Gaussian installed.
Running MLatom
To run MLatom provide a path to MLatom.py and the necessary commandline options (see in the next section), i.e. in your terminal type:
$pathToMLatom/MLatom.py [commandline options or the name of an input file with options]
In the following, notation mlatom
(it is useful to setup such an alias in your shell) is used instead of $pathToMLatom/MLatom.py
.
All options are case insensitive, i.e. you can type either
mlatom help
or
mlatom Help
with the same result (the command will print available options on your computer screen).
In order to run MLatom you have to have several input files as described below. Note that input and output file names are case sensitive! For example, xyz.dat
and XYZ.dat
are two different file names.
By default, MLatom will use all available threads on your computer. If you want to limit the number of threads to N threads, you can use optionnthreads=N
.
Getting Help and List of Options for a Current Version
You can directly request your current version of MLatom to print its available options with the command:
mlatom help
Input
MLatom can be run by providing it with the input file. Example:
mlatom myinputfile.inp
myinputfile.inp
can look like this (with comments followed after # symbol):
estAccMLmodel # one command on one line
# Lines with comments etc.
# createMLmodel # Requests creating ML model
# MLmodelOut=mlmod_E_FCI_Gaussian_20random.unf # saves the model to file
XfileIn=R_451.dat Yfile=E_FCI_451.dat # Several commands on one line
sigma=opt # Requests optimizing sigma parameter
All above options can be given directly to MLatom in a single command:
mlatom estAccMLmodel XfileIn=R_451.dat Yfile=E_FCI_451.dat sigma=opt
Along with options MLatom needs to read various files from disk depending on the task. File names should be specified using the following options:
XYZfile=[name of file with molecular XYZ coordinates]
XfileIn=[name of file with molecular descriptor (ML input) vectors]
Yfile=[name of file with reference values]
Yb=[file name with the data obtained with the baseline method for ΔML]
Yt=[file name with the reference data obtained with the target method for ΔML]
MLmodelIn=[name of file with ML model]
iTrainIn=[name of file with indices of training points]
iTestIn=[name of file with indices of test points]
iSubtrainIn=[name of file with indices of subtraining points]
iValidateIn=[name of file with indices of validation points]
iCVtestPrefIn=[prefix of names of files with indices for CVtest]
iCVoptPrefIn=[prefix of names of files with indices for CVopt]
In the requested input file does not exist, MLatom will terminate with the request to provide it. This check is not performed for files with indices involved in crossvalidation.
File extensions are arbitrary.
It is sometimes useful to use only part of the big data set. This can be requested by using option Nuse=N
, requesting that only N first entries of input files will be used.
File Formats
XYZfile
option requires file with XYZ coordinates of molecules one after another, with first line specifying number of atoms in a molecule followed by one blank line and then by Cartesian coordinates of nuclei, e.g. for three molecules:
5 C 0.000 0.000 0.000 Cl 1.776 0.000 0.000 H 0.342 1.027 0.000 H 0.342 0.513 0.890 H 0.342 0.513 0.890 5 C 0.000 0.000 0.000 Cl 1.776 0.000 0.000 H 0.343 1.027 0.000 H 0.342 0.513 0.890 H 0.342 0.513 0.890 5 C 0.000 0.000 0.000 Cl 1.776 0.000 0.000 H 0.339 1.028 0.000 H 0.342 0.513 0.890 H 0.342 0.513 0.890
Nuclear charges can be used instead of element symbols. Coordinates are given in Å.
XfileIn
requires file with input vectors, where each vector should be on one line, e.g.:
1.0093 1.0009 1.0009 1.0080 1.0229 1.0004 1.0009 0.9947 0.9738
Yfile
, Yb
, and Yt
requires a file with one reference datum per line, e.g.:
6.349 23.852 60.872
MLmodelIn
requires a file with ML model generated by MLatom, version 1.0 or version 1.1.
Files with indices should contain one index per line.
Output
MLatom prints summary of its calculations to the standard output, i.e. it is recommended to redirect it to a file, e.g.:
mlatom help > mlatom.out
It can also write files to the disk depending on the task. File names should be specified using the following options:
XfileOut=[name of file to write input vectors to]
XYZsortedFileOut=[name of file to write sorted XYZ coordinates]
MLmodelOut=[name of file to write ML model to]
YestFile=[name of file with values predicted by ML or with corrections predicted by ΔML]
YestT=[file name with the ΔML predictions estimating the target method]
YgradEstFile=[name of file to write gradients predicted by ML to]
iTrainOut=[name of file to write training point indices to]
iTestOut=[name of file to write test point indices to]
iSubtrainOut=[name of file to write subtraining point indices to]
iValidateOut=[name of file to write validation point indices to]
If output file with the same name already exists, MLatom will terminate with the request to remove or rename it. This check is not performed for files with indices generated during crossvalidation.
File extensions are arbitrary.
Option XYZsortedFileOut
only works with optionsmolDescriptor=RE molDescrType=sorted
. Option permInvNuclei=[atomic indices separated by '']
can be provided to specify which atoms to sort.
You can request additional output with debug
option. It will e.g. print the regression coefficients α when using the ML model.
Tasks Performed by MLatom
A brief overview how to request MLatom to perform its tasks. See sections below for additional options.
For all tasks at least one of both XYZfile
and XfileIn
options should be used (see Section Input).
ML operations
You can estimate accuracy of ML models, i.e. estimate its generalization error by using option estAccMLmodel
with other options:
mlatom estAccMLmodel [other options]
For default settings and other mandatory options see the corresponding sections below, specically section Model Validation.
Example:
mlatom estAccMLmodel Yfile=y.dat XYZfile=xyz.dat kernel=Gaussian sigma=opt lambda=opt
This command will request estimation of the generalization error of an ML model for molecules provided in Cartesian coordinates in xyz.dat
file and reference data in y.dat
file. Gaussian kernel will be used and hyperparameters σ and λ will be optimized.
In order to create an ML model and save it to a file on a disk, use option createMLmodel
:
mlatom createMLmodel [other options]
For both estAccMLmodel
and createMLmodel
additional input option Yfile
should be used (see Section Input).
Example:
mlatom createMLmodel Yfile=y.dat XYZfile=xyz.dat MLmodelOut=mlmod.unf kernel=Gaussian sigma=opt lambda=opt
This command will request creating an ML model for molecules provided in Cartesian coordinates in xyz.dat
file and reference data in y.dat
file and save it to mlmod.unf
file. Gaussian kernel will be used and hyperparameters σ and λ will be optimized.
Loading existing ML model from a file and performing ML calculations with this model can be done with option useMLmodel
:
mlatom useMLmodel [other options]
For useMLmodel
additional input option MLmodelIn
should be used (see Section Input).
Example:
mlatom useMLmodel MLmodelIn=mlmod.unf XYZfile=xyz.dat YestFile=yest.dat
This command will request making predictions with an ML model read from mlmod.unf
file for molecules provided in Cartesian coordinates in xyz.dat
file and save predicted values in yest.dat
file. Program will output summary of the loaded model, such as used kernel and values of hyperparameters used to create it.
All above ML operations can be also performed within ΔML approach requested by deltaLearn
. The baseline values should be provided using Yb
option. The target values for training should be provided with Yt
option. The ΔML can be saved to file specified with YestT
, while the corrections themselves to file specified with YestFile
.
Data Set Operations
Converting XYZ coordinates into an input vector (molecular descriptor) for ML
You can use XYZ2X
option to convert XYZ coordinates of a series of molecules provided in file requested by option XYZfile=[filename]
to the molecular descriptor (input) vectors for ML calculations saved in file requested by option XfileOut=[filename]
in estAccMLmodel
with other options.
Example:
mlatom XYZ2X XYZfile=xyz.dat XfileOut=x.dat
Given a data set of molecules either in XYZ format or in molecular descriptor form, you can sample their subsets (e.g. the training and test sets), by using sample
option:
mlatom sample [other options]
Basically, one can use this option to generate indices of the training, test, subtraining, and validation sets without performing ML calculations. Thus, other options used for Model Validation and Hyperparameter Tuning are applicable.
Sampling
You can specify a type of sampling into the training and other sets using option sampling=[type of sampling]
. Available types of sampling are: none
, random
, userdefined
, structurebased
, farthestpoint
.

random
: default. Simple random samplinguserdefined
: requests MLatom to read indices for the training, test, and, if necessary, for the subtraining and validation sets from files defined by optionsiTrainIn
,iTestIn
,iSubtrainIn
,iValidateIn
. Corresponding optionsNtrain
,Ntest
,Nsubtrain
, andNvalidate
can be used as well. Crossvalidation parts can be read in from files with names starting with prefixes specified by optionsiCVtestPrefIn
andiCVoptPrefIn
.structurebased
: performs structurebased sampling. Only works withmolDescriptor=RE
.farthestpoint
: farthestpoint traversal iterative procedure, which starts from two points farthest apartnone
: simply splitting the data set into the training, test, and, if necessary, training set into the subtraining and validation sets (in this order) without changing the order of indices
Structurebased Sampling from Sliced Data
Options for sorting geometries by the Euclidean distance of their corresponding ML input vector to the input vector of the equilibrium geometry and slicing the ordered data set into requested number of regions of the same size:
slice
: slice data setnslices=[number of slices]
[default = 3]XfileIn=[file with input vectors X]
eqXfileIn=[file S with input vector for the equilibrium]
This options create files xordered.dat
(input vectors sorted by distance), indices_ordered.dat
(indices of ordered data set wrt the original data set), and distances_ordered.dat
(list of Euclidean distances of ordered data points to the equilibrium). They also create directories slice1
, slice2
etc. Each of them contains three files: x.dat
, slice_indices.dat
, and slice_distances.dat
that are slices of the corresponding files of the entire data set.
Options to perform structurebased sampling to sample the desired number of data from each slice:
sampleFromSlices
: sample from each slicenslices=[number of slices]
[default = 3]Ntrain=[total integer number N of training points from all slices]
This command creates itrain.dat
files with training set indices in each slice[1...]
directory. Note: it is possible to modify sliceData.py
script to submit the jobs in parallel to the queue.
To merge sampled indices from all slices into indices files for the training, test, subtraining, and validation sets using the same order of data points as in original data set:
mergeSlices
: merges indices from slices [see sliceData help]nslices=[number of slices]
[default = 3]Ntrain=[total integer number N of training points from all slices]
This command creates four files with indices: itrain.dat
(with 4480 points for training), isubtrain.dat
(with 80% of training points also chosen using structurebased sampling), itest.dat
, and ivalidate.dat
.
ML Algorithm
You can use the following options for performing kernel ridge regression calculations:
lambda=R
: sets regularization parameter λ to a floatingpoint numberR
. Default value is 0.0. You can request optimization of this parameter withlambda=opt
, see below for more options related to hyperparameter tuning.kernel=[type of kernel]
: requests using one of the available types of kernel, which are selfexplaining.kernel=Gaussian
(set by default).kernel=Laplacian
kernel=exponential
kernel=Matern
Kernel width σ is a parameter, which can be also changed by the user using the following option:
sigma=R
: sets σ to a floatingpoint numberR
. You can request optimization of this parameter withsigma=opt
, see below for more options related to hyperparameter tuning. Default values are different for different kernels:sigma=100.0
for the Gaussian and Matérn kernelssigma=800.0
for the Laplacian and exponential kernels
In case of Matérn kernel, there is an additional integer parameter n, which is set by default to 2, and can be changed to an integer number N
using option nn=N
.
Permutation of atomic indices (especially of the same element) should not change predictions made by ML model. This can be achieved by using permutationally invariant kernel (preferred) or sorting indices of atoms in some unique way (described below in Section Molecular Descriptors). Calculations with permutationally invariant kernel can be requested by using optionpermInvKernel
and:
 by providing file with molecular geometries in XYZ format and specifying atoms to permute using options
permInvNuclei=[atomic indices separated by ''] molDescrType=permuted
.  by providing file with input vectors and specifying number of permutations using option
Nperm=[number of permutations]
. Each line of input vector file must contain input vectors with molecular descriptors concatenated for all atomic permutation of a single geometry.
Selfcorrection can be requested by option selfCorrect
. Currently it works only with four layers and file with reference values should be named y.dat
.
Molecular Descriptors
molDescriptor=[molecular descriptor]
: requests using one of the available molecular descriptors:
molDescriptor=CM
: requests using the Coulomb matrixmolDescriptor=RE
: requests using the RE descriptor (normalized inverted internuclear distances; default). It is a vector {r^{eq}/r}, where r is an internuclear distance in a current molecule and r^{eq} is an internuclear distance in the equilibrium (or other reference) structure. Equilibrium structure should be provided in a file named ‘eq.xyz’ in XYZ format.
Variants of these descriptors can be requested by option molDescrType=[type]
:
molDescrType=unsorted
: uses the same order of atoms as in input file with XYZ coordinates of molecules. Default formolDescriptor=RE
.molDescrType=sorted
: sorts atoms and ensures permutation invariance on input vector level (especially useful for sorting; when possible, permutationally invariant kernel should be prefered for ML calculations): sorts Coulomb matrix by norms of its rows for
molDescriptor=CM
(default for Coulomb matrix).  sorts atoms by the sum of their nuclear repulsions to all other atoms for
molDescriptor=RE
. Atoms to sort can be specified by optionpermInvNuclei=[atomic indices separated by '']
. If optionpermInvNuclei
is not used, all atoms are sorted.
 sorts Coulomb matrix by norms of its rows for
molDescrType=permuted
: generate multiple XYZ structures of a single geometry by permuting atoms specified with optionpermInvNuclei=[atomic indices separated by '']
, convert each of them to molecular descriptor, and concatenate the latter into a single input vector. This option is necessary to run calculations with permutationally invariant kernel.
KREG model
The KREG model is the default ML model of MLatom. It is KRR ML algorithm with the Gaussian kernel function and RE molecular descriptor.
Model Validation
ML model can be validated (generalization error can be estimated) in several ways:
 on a holdout test set not used for training. Both training and test sets can be sampled in one of the ways described above. Number of points in the subtraining and validation sets is set by options
Ntrain=R
andNtest=R
, respectively. IfR
is an integer larger or equal to 1, this number of points is sampled from the data set. IfR
is a floatingpoint number less than 1.0, it is used to define a fraction of the data set points to sample. By default, 80% of the data set points are used as the training set and remaining 20% as the test set;  by performing Nfold crossvalidation. User can request this procedure using option
CVtest
and define the number of folds N by using optionNcvTestFolds=N
. By default, 5fold crossvalidation is used. If N is equal to the number of data points, leaveoneout crossvalidation is performed. Only random or no sampling can be used for crossvalidation.  by performing leaveoneout crossvalidation. User can request this procedure using option
LOOtest
. Only random or no sampling can be used.
Hyperparameter Tuning
Gaussian, Laplacian, exponential, and Matérn kernels have σ and λ tunable hyperparameters. Their optimization can be requested with options sigma=opt
and lambda=opt
, respectively.
MLatom can tune hyperparameters either to minimize mean absolute error or to minimize rootmeansquare error as defined by option using either option minimizeError=MAE
or minimizeError=RMSE
(default), respectively. Hyperparameters can be tuned to minimize
 the error of the ML model trained on the subtraining set in a holdout validation set. Both subtraining and validation sets can be sampled from the training set in one of the ways described above. Number of points in the subtraining and validation sets is set by options
Nsubtrain=R
andNvalidate=R
, respectively. IfR
is an integer larger or equal to 1, this number of points is sampled from the training set. IfR
is a floatingpoint number less than 1.0, it is used to define a fraction of the training set points to sample. By default, 80% of the training set points are used as the subtraining set and remaining 20% as the validation set;  Nfold crossvalidation error. User can request this procedure using option
CVopt
and define the number of folds N by using optionNcvOptFolds=N
. By default, 5fold crossvalidation is used. If N is equal to the number of data points, leaveoneout crossvalidation is performed. Only random or no sampling can be used for crossvalidation.  leaveoneout crossvalidation error. User can request this procedure using option
LOOopt
. Only random or no sampling can be used.
MLatom searches optimal parameters on a logarithmic grid. After best parameters found in the first iteration, MLatom can perform more iterations of a logarithmic grid search. Number of iterations is controlled by lgOptDepth=N
keyword with N
=3 by default. User can adjust number of grid points, starting and finishing points on the grid by using the following options for
 λ hyperparameter:
NlgLambda=N
defines the number of points on the logarithmic grid (base 2). By default 6 points are used.lgLambdaL=R
Lowest value of log_{2} λ for a logarithmic grid optimization of lambda. Default value is 35.0.lgLambdaH=R
Highest value of log_{2} λ for a logarithmic grid optimization of lambda. Default value is 6.0.
 σ hyperparameter:
NlgSigma=N
defines the number of points on the logarithmic grid (base 2). By default 6 points are used.lgSigmaL=R
Lowest value of log_{2} λ for a logarithmic grid optimization of lambda. Default value is 2.0 for the Gaussian and Matérn kernels, 5.0 for the Laplacian and exponential kernels.lgSigmaH=R
Highest value of log_{2} λ for a logarithmic grid optimization of lambda. Default value is 9.0 for the Gaussian and Matérn kernels, 12.0 for the Laplacian and exponential kernels.
First Derivatives
MLatom can be also used to calculate first derivatives given a file with an existing ML model. In order to request such calculations, simply add to the options used with useMLmodel
option additional output option YgradEstFile=[name of a file to save gradients in]
.
Example:
mlatom useMLmodel MLmodelIn=mlmod.unf XYZfile=xyz.dat YgradEstFile=ygradest.dat
This command will request making predictions with an ML model read from mlmod.unf
file for molecules provided in Cartesian coordinates in xyz.dat
file and save predicted gradients in ygradest.dat
file.
Note that YestFile
cannot be used together with YgradEstFile
.
Cross Section with ML Nuclear Ensemble Approach
MLatom can accelerate the calculation of crosssection with Nuclear Ensemble Approach: paper link>>>
NewtonX and Gaussian should be available.
usage: MLatom.py crosssection [optional arguments]
optional arguments:
Nexcitations=N
number of excited states to calculate.
(default=3)nQMpoints=N
userdefined number of QM calculations for training ML. (default=0, number of QM calculations will be determined iteratively)plotQCNEA
requests plotting QCNEA cross sectiondeltaQCNEA=float
define the broadening parameter of QCNEA cross sectionplotQCSPC
requests plotting cross section obtained via single point convolution
advanced arguments (not recommended to modify):
nMaxPoints=N
maximum number of QC calculations in the iterative
procedure. (default=10000)MLpoints=N
number of ML calculations.
(default=50000)
environment variables
$NX
NewtonX environmentEnvironment for calculations with Gaussian program package. details>>>
In bash, you can for example use the following command (provide the correct path to NewtonX bin directory):export NX=/home/users/bxxue/NX/bin
required files:
 mandatory file
gaussian_optfreq.com
input file for Gaussian opt and freq calculations Alternatively, fileseq.xyz
(XYZ file with equilibrium, optimized, geometry) andnea_geoms.xyz
(file with all geometries in nuclear ensemble) can be provided.gaussian_ef.com
template file for calculating excitation energies and oscillator strengths with Gaussian.
 optional file
crosssection_ref.dat
reference cross section file calculated in format similar to that of NewtonX (1st column: DE/eV; 2nd column: lambda/nm; 3rd column: sigma/A^2)eq.xyz
file with optimized geometry (has to be used together withnea_geoms.xyz
)nea_geoms.xyz
file with all geometries in nuclear ensemble (has to be used together witheq.xyz
)E1.dat E2.dat ...
andf1.dat f2.dat ...
files that stores the exciting energy and oscillator strength per line which correspond tonea_geoms.xyz
.
output files:

crosssection/crosssection_mlnea.dat
: crosssection spectra calculated with MLNEA methodcrosssection/crosssection_qcnea.dat
: crosssection spectra calculated with QCNEA methodcrosssection/crosssection_spc.dat
: crosssection spectra calculated with singlepointconvolutioncrosssection/plot.png
: the plotting that contains crosssection calculated with different kinds of method.
Support
If you want to collaborate, have some suggestions for improving the program, or want to report a bug, please write to me.