Manual

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 sub-training 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 cross-validation.

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.

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 sub-training 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 cross-validation.

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.

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.

Self-correction can be requested by option selfCorrect. Currently it works only with four layers and file with reference values should be named y.dat.

AIQM1 (artificial intelligence–quantum mechanical method 1) is a general-purpose ML-based method that approaches high-level QM accuracy. Please check this standalone page for more details.

geomopt is a task for the geometry optimization of the input geometry with any existing ML model generated or built in MLatom.

To perform this task, the trained model (defined with MLmodelIn option) or build-in model (AIQM1 or ANI-1ccx, etc.), and the input geometry (XYZfile) are needed. Several optimization programs (Gaussian, ASE, SciPy, depends on you system set-up) can be chosen via optprog option.

For more details and examples, please check AIQM1 tutorial and the HoF tutorial.

freq is a task for the frequency calculations that utilize ML models. Since the analytical Hessian needs to be calculated, currently only AIQM1 and other ANI models support this task.

To perform this task, you need to select your ML model and provide the optimized geometry (obtained by geomopt).

For more details and examples, please check AIQM1 tutorial and the HoF tutorial.

Another ML operation, the task learning curve can automatically train models and estimate their accuracy, then give a summary file in comma separated values (CSV) format. Use learningCurve option to perform this task. The options for this task, just as those for estAccMLmodel, except for the Ntrain which is replaced by lcNtrains and a extra option lcNrepeats. As their names show, the choice of traning set sizes and number of repeats are defined in these two new options.

Example:

mlatom learningCurve Yfile=y.dat XYZfile=xyz.dat kernel=Gaussian sigma=opt lambda=opt lcNtrains=100,250,500,1000,2500,5000,10000 lcNrepeats=64,32,16,8,4,2,1

With this command training set sizes lited in lcNtrains will be tested repeatedly for 64, 32, 16, 8, 4, 2, 1 time(s), respectively. All data generated (including csv reports) will be stored in the folder learningCurve under current directory.

MLatom can accelerate the calculation of cross-section with Nuclear Ensemble Approach: paper link>>>

Newton-X and Gaussian should be available.

Requirements for ML-NEA

To run ML-NEA calculations of absorption cross sections, you also need to define some environment:

1. Install Newton-X (NX, version==2.2)
2. use export NX=/path/to/Newton-X to define the $NX
3. install matplotlib with the command python3 -m pip install matplotlib
4. Have Gaussian installed.

usage: MLatom.py cross-section [optional arguments] 

optional arguments:

• Nexcitations=N number of excited states to calculate.
  (default=3)
• nQMpoints=N user-defined number of QM calculations for training ML. (default=0, number of QM calculations will be determined iteratively)
• plotQCNEA requests plotting QC-NEA cross section
• deltaQCNEA=float define the broadening parameter of QC-NEA cross section
• plotQCSPC 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 Newton-X environment
• Environment for calculations with Gaussian program package. details>>>

In bash, you can for example use the following command (provide the correct path to Newton-X bin directory):
export NX=/home/users/bxxue/NX/bin

required files:

1. mandatory file
   1. gaussian_optfreq.com input file for Gaussian opt and freq calculations Alternatively, files eq.xyz (XYZ file with equilibrium, optimized, geometry) and nea_geoms.xyz (file with all geometries in nuclear ensemble) can be provided.
   2. gaussian_ef.com template file for calculating excitation energies and oscillator strengths with Gaussian. 
2. optional file
   1. cross-section_ref.dat reference cross section file calculated in format similar to that of Newton-X (1st column: DE/eV; 2nd column: lambda/nm; 3rd column: sigma/A^2)
   2. eq.xyz file with optimized geometry (has to be used together with nea_geoms.xyz)
   3. nea_geoms.xyz file with all geometries in nuclear ensemble (has to be used together with eq.xyz)
   4. E1.dat  E2.dat ... and f1.dat  f2.dat ... files that stores the exciting energy and oscillator strength per line which correspond to nea_geoms.xyz.

output files:

1. cross-section/cross-section_ml-nea.dat: cross-section spectra calculated with ML-NEA method
2. cross-section/cross-section_qc-nea.dat: cross-section spectra calculated with QC-NEA method
3. cross-section/cross-section_spc.dat: cross-section spectra calculated with single-point-convolution
4. cross-section/plot.png: the plotting that contains cross-section calculated with different kinds of method.

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, sub-training, and validation sets without performing ML calculations. Thus, other options used for Model Validation and Hyperparameter Tuning are applicable.

This task requires reference data and estimated data to give a statistical report.

For reference data at least one of these arguments below is required:
Yfile=S YgradXYZfile=S 

And for estimated data, correspondingly:
YestFile=S YgradXYZestFile=S

Example:

MLatom.py analyze Yfile=en.dat YestFile=enest.dat

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, user-defined, structure-based, farthest-point.

• random: default. Simple random sampling
• user-defined: requests MLatom to read indices for the training, test, and, if necessary, for the subtraining and validation sets from files defined by options iTrainIn, iTestIn, iSubtrainIn, iValidateIn. Corresponding options Ntrain, Ntest, Nsubtrain, and Nvalidate can be used as well. Cross-validation parts can be read in from files with names starting with prefixes specified by options iCVtestPrefIn and iCVoptPrefIn.
• structure-based: performs structure-based sampling. Only works with  molDescriptor=RE.
• farthest-point: farthest-point traversal iterative procedure, which starts from two points farthest apart
• none: 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

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 set
  • nslices=[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 structure-based sampling to sample the desired number of data from each slice:

• sampleFromSlices: sample from each slice
  • nslices=[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, sub-training, 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 structure-based sampling), itest.dat, and ivalidate.dat.