mlatom 3.0.0__tar.gz

mlatom-3.0.0/LICENSE.txt

@@ -0,0 +1,251 @@
+Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International Public License
+
+By exercising the Licensed Rights (defined below), You accept and agree to be
+bound by the terms and conditions of this Creative Commons
+Attribution-NonCommercial-NoDerivatives 4.0 International Public License
+("Public License"). To the extent this Public License may be interpreted as a
+contract, You are granted the Licensed Rights in consideration of Your
+acceptance of these terms and conditions, and the Licensor grants You such
+rights in consideration of benefits the Licensor receives from making the
+Licensed Material available under these terms and conditions.
+
+Section 1 – Definitions.
+
+    a. Adapted Material means material subject to Copyright and Similar Rights
+       that is derived from or based upon the Licensed Material and in which
+       the Licensed Material is translated, altered, arranged, transformed, or
+       otherwise modified in a manner requiring permission under the Copyright
+       and Similar Rights held by the Licensor. For purposes of this Public
+       License, where the Licensed Material is a musical work, performance, or
+       sound recording, Adapted Material is always produced where the Licensed
+       Material is synched in timed relation with a moving image.
+    b. Copyright and Similar Rights means copyright and/or similar rights
+       closely related to copyright including, without limitation,
+       performance, broadcast, sound recording, and Sui Generis Database
+       Rights, without regard to how the rights are labeled or categorized.
+       For purposes of this Public License, the rights specified in Section
+       2(b)(1)-(2) are not Copyright and Similar Rights.
+    c. Effective Technological Measures means those measures that, in the
+       absence of proper authority, may not be circumvented under laws
+       fulfilling obligations under Article 11 of the WIPO Copyright Treaty
+       adopted on December 20, 1996, and/or similar international agreements.
+    d. Exceptions and Limitations means fair use, fair dealing, and/or any
+       other exception or limitation to Copyright and Similar Rights that
+       applies to Your use of the Licensed Material.
+    e. Licensed Material means the artistic or literary work, database, or
+       other material to which the Licensor applied this Public License.
+    f. Licensed Rights means the rights granted to You subject to the terms
+       and conditions of this Public License, which are limited to all
+       Copyright and Similar Rights that apply to Your use of the Licensed
+       Material and that the Licensor has authority to license.
+    g. Licensor means the individual(s) or entity(ies) granting rights under
+       this Public License.
+    h. NonCommercial means not primarily intended for or directed towards
+       commercial advantage or monetary compensation. For purposes of this
+       Public License, the exchange of the Licensed Material for other
+       material subject to Copyright and Similar Rights by digital
+       file-sharing or similar means is NonCommercial provided there is no
+       payment of monetary compensation in connection with the exchange.
+    i. Share means to provide material to the public by any means or process
+       that requires permission under the Licensed Rights, such as
+       reproduction, public display, public performance, distribution,
+       dissemination, communication, or importation, and to make material
+       available to the public including in ways that members of the public
+       may access the material from a place and at a time individually chosen
+       by them.
+    j. Sui Generis Database Rights means rights other than copyright resulting
+       from Directive 96/9/EC of the European Parliament and of the Council of
+       11 March 1996 on the legal protection of databases, as amended and/or
+       succeeded, as well as other essentially equivalent rights anywhere in
+       the world.
+    k. You means the individual or entity exercising the Licensed Rights under
+       this Public License. Your has a corresponding meaning.
+
+Section 2 – Scope.
+
+    a. License grant.
+        1. Subject to the terms and conditions of this Public License, the
+           Licensor hereby grants You a worldwide, royalty-free,
+           non-sublicensable, non-exclusive, irrevocable license to exercise
+           the Licensed Rights in the Licensed Material to:
+            A. reproduce and Share the Licensed Material, in whole or in part,
+               for NonCommercial purposes only; and
+            B. produce and reproduce, but not Share, Adapted Material for
+               NonCommercial purposes only.
+        2. Exceptions and Limitations. For the avoidance of doubt, where
+           Exceptions and Limitations apply to Your use, this Public License
+           does not apply, and You do not need to comply with its terms and
+           conditions.
+        3. Term. The term of this Public License is specified in Section 6(a).
+        4. Media and formats; technical modifications allowed. The Licensor
+           authorizes You to exercise the Licensed Rights in all media and
+           formats whether now known or hereafter created, and to make
+           technical modifications necessary to do so. The Licensor waives
+           and/or agrees not to assert any right or authority to forbid You
+           from making technical modifications necessary to exercise the
+           Licensed Rights, including technical modifications necessary to
+           circumvent Effective Technological Measures. For purposes of this
+           Public License, simply making modifications authorized by this
+           Section 2(a)(4) never produces Adapted Material.
+        5. Downstream recipients.
+            A. Offer from the Licensor – Licensed Material. Every recipient of
+               the Licensed Material automatically receives an offer from the
+               Licensor to exercise the Licensed Rights under the terms and
+               conditions of this Public License.
+            B. No downstream restrictions. You may not offer or impose any
+               additional or different terms or conditions on, or apply any
+               Effective Technological Measures to, the Licensed Material if
+               doing so restricts exercise of the Licensed Rights by any
+               recipient of the Licensed Material.
+        6. No endorsement. Nothing in this Public License constitutes or may
+           be construed as permission to assert or imply that You are, or that
+           Your use of the Licensed Material is, connected with, or sponsored,
+           endorsed, or granted official status by, the Licensor or others
+           designated to receive attribution as provided in Section
+           3(a)(1)(A)(i).
+
+    b. Other rights.
+        1. Moral rights, such as the right of integrity, are not licensed
+           under this Public License, nor are publicity, privacy, and/or other
+           similar personality rights; however, to the extent possible, the
+           Licensor waives and/or agrees not to assert any such rights held by
+           the Licensor to the limited extent necessary to allow You to
+           exercise the Licensed Rights, but not otherwise.
+        2. Patent and trademark rights are not licensed under this Public
+           License.
+        3. To the extent possible, the Licensor waives any right to collect
+           royalties from You for the exercise of the Licensed Rights, whether
+           directly or through a collecting society under any voluntary or
+           waivable statutory or compulsory licensing scheme. In all other
+           cases the Licensor expressly reserves any right to collect such
+           royalties, including when the Licensed Material is used other than
+           for NonCommercial purposes.
+
+Section 3 – License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to the following conditions.
+
+    a. Attribution.
+
+        1. If You Share the Licensed Material, You must:
+            A. retain the following if it is supplied by the Licensor with the
+               Licensed Material:
+                i. identification of the creator(s) of the Licensed Material
+                   and any others designated to receive attribution, in any
+                   reasonable manner requested by the Licensor (including by
+                   pseudonym if designated);
+                ii. a copyright notice;
+                iii. a notice that refers to this Public License;
+                iv. a notice that refers to the disclaimer of warranties;
+                v. a URI or hyperlink to the Licensed Material to the extent
+                   reasonably practicable;
+            B. indicate if You modified the Licensed Material and retain an
+               indication of any previous modifications; and
+            C. indicate the Licensed Material is licensed under this Public
+               License, and include the text of, or the URI or hyperlink to,
+               this Public License.
+
+            For the avoidance of doubt, You do not have permission under this
+            Public License to Share Adapted Material.
+
+        2. You may satisfy the conditions in Section 3(a)(1) in any reasonable
+           manner based on the medium, means, and context in which You Share
+           the Licensed Material. For example, it may be reasonable to satisfy
+           the conditions by providing a URI or hyperlink to a resource that
+           includes the required information.
+        3. If requested by the Licensor, You must remove any of the
+           information required by Section 3(a)(1)(A) to the extent reasonably
+           practicable.
+
+Section 4 – Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that apply to
+Your use of the Licensed Material:
+
+    a. for the avoidance of doubt, Section 2(a)(1) grants You the right to
+       extract, reuse, reproduce, and Share all or a substantial portion of
+       the contents of the database for NonCommercial purposes only and
+       provided You do not Share Adapted Material;
+    b. if You include all or a substantial portion of the database contents in
+       a database in which You have Sui Generis Database Rights, then the
+       database in which You have Sui Generis Database Rights (but not its
+       individual contents) is Adapted Material; and
+    c. You must comply with the conditions in Section 3(a) if You Share all or
+       a substantial portion of the contents of the database.
+
+For the avoidance of doubt, this Section 4 supplements and does not replace
+Your obligations under this Public License where the Licensed Rights include
+other Copyright and Similar Rights.
+
+Section 5 – Disclaimer of Warranties and Limitation of Liability.
+
+    a. Unless otherwise separately undertaken by the Licensor, to the extent
+       possible, the Licensor offers the Licensed Material as-is and
+       as-available, and makes no representations or warranties of any kind
+       concerning the Licensed Material, whether express, implied, statutory,
+       or other. This includes, without limitation, warranties of title,
+       merchantability, fitness for a particular purpose, non-infringement,
+       absence of latent or other defects, accuracy, or the presence or
+       absence of errors, whether or not known or discoverable. Where
+       disclaimers of warranties are not allowed in full or in part, this
+       disclaimer may not apply to You.
+    b. To the extent possible, in no event will the Licensor be liable to You
+       on any legal theory (including, without limitation, negligence) or
+       otherwise for any direct, special, indirect, incidental, consequential,
+       punitive, exemplary, or other losses, costs, expenses, or damages
+       arising out of this Public License or use of the Licensed Material,
+       even if the Licensor has been advised of the possibility of such
+       losses, costs, expenses, or damages. Where a limitation of liability is
+       not allowed in full or in part, this limitation may not apply to You.
+    c. The disclaimer of warranties and limitation of liability provided above
+       shall be interpreted in a manner that, to the extent possible, most
+       closely approximates an absolute disclaimer and waiver of all
+       liability.
+
+Section 6 – Term and Termination.
+
+    a. This Public License applies for the term of the Copyright and Similar
+       Rights licensed here. However, if You fail to comply with this Public
+       License, then Your rights under this Public License terminate
+       automatically.
+    b. Where Your right to use the Licensed Material has terminated under
+       Section 6(a), it reinstates:
+        1. automatically as of the date the violation is cured, provided it is
+           cured within 30 days of Your discovery of the violation; or
+        2. upon express reinstatement by the Licensor.
+
+      For the avoidance of doubt, this Section 6(b) does not affect any right
+      the Licensor may have to seek remedies for Your violations of this
+      Public License.
+
+    c. For the avoidance of doubt, the Licensor may also offer the Licensed
+       Material under separate terms or conditions or stop distributing the
+       Licensed Material at any time; however, doing so will not terminate
+       this Public License.
+    d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License.
+
+Section 7 – Other Terms and Conditions.
+
+    a. The Licensor shall not be bound by any additional or different terms or
+       conditions communicated by You unless expressly agreed.
+    b. Any arrangements, understandings, or agreements regarding the Licensed
+       Material not stated herein are separate from and independent of the
+       terms and conditions of this Public License.
+
+Section 8 – Interpretation.
+
+    a. For the avoidance of doubt, this Public License does not, and shall not
+       be interpreted to, reduce, limit, restrict, or impose conditions on any
+       use of the Licensed Material that could lawfully be made without
+       permission under this Public License.
+    b. To the extent possible, if any provision of this Public License is
+       deemed unenforceable, it shall be automatically reformed to the minimum
+       extent necessary to make it enforceable. If the provision cannot be
+       reformed, it shall be severed from this Public License without
+       affecting the enforceability of the remaining terms and conditions.
+    c. No term or condition of this Public License will be waived and no
+       failure to comply consented to unless expressly agreed to by the Licensor.
+    d. Nothing in this Public License constitutes or may be interpreted as a
+       limitation upon, or waiver of, any privileges and immunities that apply
+       to the Licensor or You, including from the legal processes of any
+       jurisdiction or authority.

mlatom-3.0.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.1
+Name: mlatom
+Version: 3.0.0
+Summary: A Package for Atomistic Simulations with Machine Learning
+Home-page: http://mlatom.com
+Author: Pavlo O. Dral
+Author-email: admin@mlatom.com
+License: MIT (modified)
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Fortran
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Environment :: Console
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+
+# Brief Introduction
+A Package for Atomistic Simulations with Machine Learning
+
+**manual**: http://mlatom.com/manual/  
+**tutorial**: http://mlatom.com/tutorial/ 
+
+
+#  Tasks Performed by MLatom
+A brief overview of MLatom capabilities (see above links for more up-to-date version). See sections below for more details.
+
+## Tasks
+- Estimating accuracy of ML models.
+- Creating ML model and saving it to a file.
+- Loading existing ML model from a file and performing ML calculations with this model.
+- ML-accelerated calculation of absorption spectra within nuclear ensemble approach
+- Learning curves
+- ML-two photon absorption
+
+## Data Set Operations
+- Converting XYZ coordinates into an input vector (molecular descriptor) for ML.
+- Sampling subsets from a data set.
+
+
+# Sampling
+- 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.
+- random sampling.
+- user-defined: requests MLatom to read indices for the training, test, and, if necessary, for the subtraining and validation sets from files.
+- [ structure-based sampling ](http://mlatom.com/self-correcting-machine-learning-and-structure-based-sampling/)
+  - from unsliced and sliced data
+- [ farthest-point traversal iterative procedure ](https://en.wikipedia.org/wiki/Farthest-first_traversal), which starts from two points farthest apart.
+
+
+# ML Algorithm
+[ Kernel ridge regression](https://web.stanford.edu/~hastie/ElemStatLearn/) with the following kernels:
+- [ Gaussian ](https://doi.org/10.1103/PhysRevLett.108.058301).
+- [ Laplacian ](https://doi.org/10.1103/PhysRevLett.108.058301).
+- exponential.
+- [ Matérn ](http://dx.doi.org/10.1198/jasa.2010.tm09420) ([ details of implementation ](http://dx.doi.org/10.1021/acs.jpclett.8b02469)).
+Permutationally invariant kernel and self-correction are also supported.
+
+
+# Hybrid QM/ML Approaches
+[ Δ-machine learning ](http://dx.doi.org/10.1021/acs.jctc.5b00099).
+
+
+# Molecular Descriptors
+- [ Coulomb matrix ](https://doi.org/10.1103/PhysRevLett.108.058301)
+  - [ sorted by norms of its rows ](http://dx.doi.org/10.1021/ct400195d);
+  - unsorted;
+  - permuted.
+- [ Normalized inverse internuclear distances (RE descriptor)](http://mlatom.com/self-correcting-machine-learning-and-structure-based-sampling/)
+  - sorted for user-defined atoms by the sum of their nuclear repulsions to all other atoms;
+  - unsorted;
+  - permuted.
+
+
+# ML models
+The [ KREG (Kernel-ridge-regression using RE descriptor and the Gaussian kernel function )](http://dx.doi.org/10.1021/acs.jpclett.8b02469) model is the default ML method.
+
+## General-purpose ML models
+- AIQM1 (requires interfaces to other programs as described in http://MLatom.com/AIQM1)
+- Models available via interface to [TorchANI](https://doi.org/10.1021/acs.jcim.0c00451)
+  - ANI-1x
+  - ANI-1ccx
+  - ANI-2x
+
+# Model Validation
+[ ML model can be validated (generalization error can be estimated) in several ways: ](https://web.stanford.edu/~hastie/ElemStatLearn/)
+
+- on a hold-out test set not used for training. Both training and test sets can be sampled in one of the ways described above;
+- by performing N-fold cross-validation. User can define the number of folds N. If N is equal to the number of data points, leave-one-out cross-validation is performed. Only random or no sampling can be used for cross-validation.
+- by performing leave-one-out cross-validation (special case of N-fold cross-validation).
+MLatom prints out mean absolute error (MAE), mean signed error (MSE), root-mean-squared error (RMSE), mean values of reference and estimated values, largest positive and negative outliers, correlation coefficient and its squared value R2 as well as coefficients of linear regression and corresponding standard deviations.
+
+
+# Hyperparameter Tuning
+Gaussian, Laplacian, and Matérn kernels have σ and λ tunable hyperparameters. MLatom can determine them by performing user-defined number of iterations of hyperparameter optimization on a logarithmic grid. User can adjust number of grid points, starting and finishing points on the grid. Hyperparameter are tuned to minimize either mean absolute error or root-mean-square error as defined by the user. [ Hyperparameters can be tuned to minimize ](https://web.stanford.edu/~hastie/ElemStatLearn/)
+
+- the error of the ML model trained on the subtraining set in a hold-out validation set. Both subtraining and validation sets are parts of the training set, which can be used at the end with optimal parameters for training the final ML model. These sets ideally should not overlap and can be [ sampled ](http://mlatom.com/features/#Sampling) from the training set in one of the ways described above;
+- N-fold cross-validation error. User can define the number of folds N. If N is equal to the number of data points, leave-one-out cross-validation is performed. Only random or no sampling can be used for cross-validation.
+
+Note that hyperparameter tuning can be performed together with model validation. This means that for example one can perform outer loop of the cross-validation for model validation and tune hyperparameters via inner loop of the cross-validation.
+
+Apart from natively implemented logarithmic grid search for hyperparameters, MLatom also provides the interface to the [ hyperopt package ](http://hyperopt.github.io/hyperopt/) implementing hyperparameter optimization using Bayesian methods with Tree-structured Parzen Estimator (TPE).
+
+
+# First Derivatives
+MLatom can be also used to estimate first derivatives from an ML model. Two scenarios are possible:
+
+- partial derivatives are calculated for each dimension of given input vectors (analytical derivatives for Gaussian and Matern kernels);
+- first derivatives are calculated in XYZ coordinates for input files containing molecular XYZ coordinates (analytical derivatives for the RE and Coulomb matrix descriptors).
+- derivatives for interfaced models
+
+
+# UV/vis spectra
+MLatom can significantly accelerate the calculation of cross-section with the Nuclear Ensemble Approach (NEA).
+
+In brief, this feature uses fewer QC calculation to achieve higher precision and reduce computational cost. You can find more detail on this paper (please cite it when using this feature):
+
+> Bao-Xin Xue, Mario Barbatti, Pavlo O. Dral, [ Machine Learning for Absorption Cross Sections ](https://doi.org/10.1021/acs.jpca.0c05310), J. Phys. Chem. A 2020, 124, 7199–7210. DOI: 10.1021/acs.jpca.0c05310.
+
+# Interfaces to 3<sup>rd</sup>-party software
+MLatom also provides interfaces to some third-party software where extra ML model types are natively implemented. It allows users to access other popular ML model types within MLatom's workflow. Currently available third-party model types are:
+
+- [ANI](https://doi.org/10.1039/c6sc05720a) (through [TorchANI](https://doi.org/10.1021/acs.jcim.0c00451)) 
+- [DeepPot-SE](https://papers.nips.cc/paper/2018/hash/e2ad76f2326fbc6b56a45a56c59fafdb-Abstract.html) and [DPMD](https://doi.org/10.1103/PhysRevLett.120.143001) (through [DeePMD-kit](https://doi.org/10.1016/j.cpc.2018.03.016)) 
+- [GAP](https://doi.org/10.1103/Physrevlett.104.136403)-[SOAP](https://doi.org/10.1103/physrevb.87.184115) (through [GAP](www.libatoms.org) suite and [QUIP](http://github.com/libAtoms/QUIP))  
+- [PhysNet](https://doi.org/10.1021/acs.jctc.9b00181) (through [PhysNet](github.com/MMunibas/PhysNet)) 
+- [sGDML](https://doi.org/10.1038/s41467-018-06169-2) (through [sGDML](www.sgdml.org)) 
+
+# About Program
+MLatom: a Package for Atomistic Simulations with Machine Learning    
+Version 2.3.3
+http://mlatom.com/                             
+                                                                           
+Copyright (c) 2013-2022 Pavlo O. Dral                   
+http://dr-dral.com/                            
+                                                                           
+All rights reserved. This work is licensed under the [Attribution-NonCommercial-NoDerivatives 4.0 International](http://creativecommons.org/licenses/by-nc-nd/4.0/) license. See LICENSE.CC-BY-NC-ND-4.0.  
+The above copyright notice and this permission notice shall be included  in all copies or substantial portions of the Software.           
+The software is provided "as is", without warranty of any kind, express  or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.                                   
+                                                                           
+Cite as: 
+
+1. Pavlo O. Dral, J. Comput. Chem. 2019, 40, 2339-2347             
+2. Pavlo O. Dral, Fuchun Ge, Bao-Xin Xue, Yi-Fan Hou, Max Pinheiro Jr, Jianxing Huang, Mario Barbatti, Top. Curr. Chem. 2021, 379, 27              
+3. Pavlo O. Dral, Peikun Zheng, Bao-Xin Xue, Fuchun Ge, Yi-Fan Hou, Max Pinheiro Jr, Yuming Su, Yiheng Dai, Yangtao Chen, MLatom: A Package for Atomistic Simulations with Machine Learning, version 2.3.3, Xiamen University, Xiamen, China, 2013-2022.               
+
+
+# License
+
+This work is licensed under the [Attribution-NonCommercial-NoDerivatives 4.0 International](http://creativecommons.org/licenses/by-nc-nd/4.0/) license. See LICENSE.CC-BY-NC-ND-4.0.
+
+<a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-nd/4.0/88x31.png" /></a>

mlatom-3.0.0/README.md

@@ -0,0 +1,134 @@
+# Brief Introduction
+A Package for Atomistic Simulations with Machine Learning
+
+**manual**: http://mlatom.com/manual/  
+**tutorial**: http://mlatom.com/tutorial/ 
+
+
+#  Tasks Performed by MLatom
+A brief overview of MLatom capabilities (see above links for more up-to-date version). See sections below for more details.
+
+## Tasks
+- Estimating accuracy of ML models.
+- Creating ML model and saving it to a file.
+- Loading existing ML model from a file and performing ML calculations with this model.
+- ML-accelerated calculation of absorption spectra within nuclear ensemble approach
+- Learning curves
+- ML-two photon absorption
+
+## Data Set Operations
+- Converting XYZ coordinates into an input vector (molecular descriptor) for ML.
+- Sampling subsets from a data set.
+
+
+# Sampling
+- 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.
+- random sampling.
+- user-defined: requests MLatom to read indices for the training, test, and, if necessary, for the subtraining and validation sets from files.
+- [ structure-based sampling ](http://mlatom.com/self-correcting-machine-learning-and-structure-based-sampling/)
+  - from unsliced and sliced data
+- [ farthest-point traversal iterative procedure ](https://en.wikipedia.org/wiki/Farthest-first_traversal), which starts from two points farthest apart.
+
+
+# ML Algorithm
+[ Kernel ridge regression](https://web.stanford.edu/~hastie/ElemStatLearn/) with the following kernels:
+- [ Gaussian ](https://doi.org/10.1103/PhysRevLett.108.058301).
+- [ Laplacian ](https://doi.org/10.1103/PhysRevLett.108.058301).
+- exponential.
+- [ Matérn ](http://dx.doi.org/10.1198/jasa.2010.tm09420) ([ details of implementation ](http://dx.doi.org/10.1021/acs.jpclett.8b02469)).
+Permutationally invariant kernel and self-correction are also supported.
+
+
+# Hybrid QM/ML Approaches
+[ Δ-machine learning ](http://dx.doi.org/10.1021/acs.jctc.5b00099).
+
+
+# Molecular Descriptors
+- [ Coulomb matrix ](https://doi.org/10.1103/PhysRevLett.108.058301)
+  - [ sorted by norms of its rows ](http://dx.doi.org/10.1021/ct400195d);
+  - unsorted;
+  - permuted.
+- [ Normalized inverse internuclear distances (RE descriptor)](http://mlatom.com/self-correcting-machine-learning-and-structure-based-sampling/)
+  - sorted for user-defined atoms by the sum of their nuclear repulsions to all other atoms;
+  - unsorted;
+  - permuted.
+
+
+# ML models
+The [ KREG (Kernel-ridge-regression using RE descriptor and the Gaussian kernel function )](http://dx.doi.org/10.1021/acs.jpclett.8b02469) model is the default ML method.
+
+## General-purpose ML models
+- AIQM1 (requires interfaces to other programs as described in http://MLatom.com/AIQM1)
+- Models available via interface to [TorchANI](https://doi.org/10.1021/acs.jcim.0c00451)
+  - ANI-1x
+  - ANI-1ccx
+  - ANI-2x
+
+# Model Validation
+[ ML model can be validated (generalization error can be estimated) in several ways: ](https://web.stanford.edu/~hastie/ElemStatLearn/)
+
+- on a hold-out test set not used for training. Both training and test sets can be sampled in one of the ways described above;
+- by performing N-fold cross-validation. User can define the number of folds N. If N is equal to the number of data points, leave-one-out cross-validation is performed. Only random or no sampling can be used for cross-validation.
+- by performing leave-one-out cross-validation (special case of N-fold cross-validation).
+MLatom prints out mean absolute error (MAE), mean signed error (MSE), root-mean-squared error (RMSE), mean values of reference and estimated values, largest positive and negative outliers, correlation coefficient and its squared value R2 as well as coefficients of linear regression and corresponding standard deviations.
+
+
+# Hyperparameter Tuning
+Gaussian, Laplacian, and Matérn kernels have σ and λ tunable hyperparameters. MLatom can determine them by performing user-defined number of iterations of hyperparameter optimization on a logarithmic grid. User can adjust number of grid points, starting and finishing points on the grid. Hyperparameter are tuned to minimize either mean absolute error or root-mean-square error as defined by the user. [ Hyperparameters can be tuned to minimize ](https://web.stanford.edu/~hastie/ElemStatLearn/)
+
+- the error of the ML model trained on the subtraining set in a hold-out validation set. Both subtraining and validation sets are parts of the training set, which can be used at the end with optimal parameters for training the final ML model. These sets ideally should not overlap and can be [ sampled ](http://mlatom.com/features/#Sampling) from the training set in one of the ways described above;
+- N-fold cross-validation error. User can define the number of folds N. If N is equal to the number of data points, leave-one-out cross-validation is performed. Only random or no sampling can be used for cross-validation.
+
+Note that hyperparameter tuning can be performed together with model validation. This means that for example one can perform outer loop of the cross-validation for model validation and tune hyperparameters via inner loop of the cross-validation.
+
+Apart from natively implemented logarithmic grid search for hyperparameters, MLatom also provides the interface to the [ hyperopt package ](http://hyperopt.github.io/hyperopt/) implementing hyperparameter optimization using Bayesian methods with Tree-structured Parzen Estimator (TPE).
+
+
+# First Derivatives
+MLatom can be also used to estimate first derivatives from an ML model. Two scenarios are possible:
+
+- partial derivatives are calculated for each dimension of given input vectors (analytical derivatives for Gaussian and Matern kernels);
+- first derivatives are calculated in XYZ coordinates for input files containing molecular XYZ coordinates (analytical derivatives for the RE and Coulomb matrix descriptors).
+- derivatives for interfaced models
+
+
+# UV/vis spectra
+MLatom can significantly accelerate the calculation of cross-section with the Nuclear Ensemble Approach (NEA).
+
+In brief, this feature uses fewer QC calculation to achieve higher precision and reduce computational cost. You can find more detail on this paper (please cite it when using this feature):
+
+> Bao-Xin Xue, Mario Barbatti, Pavlo O. Dral, [ Machine Learning for Absorption Cross Sections ](https://doi.org/10.1021/acs.jpca.0c05310), J. Phys. Chem. A 2020, 124, 7199–7210. DOI: 10.1021/acs.jpca.0c05310.
+
+# Interfaces to 3<sup>rd</sup>-party software
+MLatom also provides interfaces to some third-party software where extra ML model types are natively implemented. It allows users to access other popular ML model types within MLatom's workflow. Currently available third-party model types are:
+
+- [ANI](https://doi.org/10.1039/c6sc05720a) (through [TorchANI](https://doi.org/10.1021/acs.jcim.0c00451)) 
+- [DeepPot-SE](https://papers.nips.cc/paper/2018/hash/e2ad76f2326fbc6b56a45a56c59fafdb-Abstract.html) and [DPMD](https://doi.org/10.1103/PhysRevLett.120.143001) (through [DeePMD-kit](https://doi.org/10.1016/j.cpc.2018.03.016)) 
+- [GAP](https://doi.org/10.1103/Physrevlett.104.136403)-[SOAP](https://doi.org/10.1103/physrevb.87.184115) (through [GAP](www.libatoms.org) suite and [QUIP](http://github.com/libAtoms/QUIP))  
+- [PhysNet](https://doi.org/10.1021/acs.jctc.9b00181) (through [PhysNet](github.com/MMunibas/PhysNet)) 
+- [sGDML](https://doi.org/10.1038/s41467-018-06169-2) (through [sGDML](www.sgdml.org)) 
+
+# About Program
+MLatom: a Package for Atomistic Simulations with Machine Learning    
+Version 2.3.3
+http://mlatom.com/                             
+                                                                           
+Copyright (c) 2013-2022 Pavlo O. Dral                   
+http://dr-dral.com/                            
+                                                                           
+All rights reserved. This work is licensed under the [Attribution-NonCommercial-NoDerivatives 4.0 International](http://creativecommons.org/licenses/by-nc-nd/4.0/) license. See LICENSE.CC-BY-NC-ND-4.0.  
+The above copyright notice and this permission notice shall be included  in all copies or substantial portions of the Software.           
+The software is provided "as is", without warranty of any kind, express  or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.                                   
+                                                                           
+Cite as: 
+
+1. Pavlo O. Dral, J. Comput. Chem. 2019, 40, 2339-2347             
+2. Pavlo O. Dral, Fuchun Ge, Bao-Xin Xue, Yi-Fan Hou, Max Pinheiro Jr, Jianxing Huang, Mario Barbatti, Top. Curr. Chem. 2021, 379, 27              
+3. Pavlo O. Dral, Peikun Zheng, Bao-Xin Xue, Fuchun Ge, Yi-Fan Hou, Max Pinheiro Jr, Yuming Su, Yiheng Dai, Yangtao Chen, MLatom: A Package for Atomistic Simulations with Machine Learning, version 2.3.3, Xiamen University, Xiamen, China, 2013-2022.               
+
+
+# License
+
+This work is licensed under the [Attribution-NonCommercial-NoDerivatives 4.0 International](http://creativecommons.org/licenses/by-nc-nd/4.0/) license. See LICENSE.CC-BY-NC-ND-4.0.
+
+<a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-nd/4.0/88x31.png" /></a>

mlatom-3.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mlatom-3.0.0/setup.py

@@ -0,0 +1,82 @@
+from setuptools import setup, find_packages
+from setuptools.command.install_scripts import install_scripts
+from contextlib import suppress
+from pathlib import Path
+import os
+import sys
+
+pkg_name = "mlatom"
+mlatom_script = 'mlatom'
+site_pkg = ''
+def modify_mlatom_script(script_path: str):
+    global site_pkg
+    for path in sys.path:
+        with suppress(BaseException):
+            for path_dir in os.listdir(path):
+                if pkg_name in path_dir:
+                    site_pkg = path
+                    print(site_pkg)
+    MLatom_py_file = os.path.join(site_pkg, pkg_name, 'MLatom.py')
+    content = f"""#!/bin/bash
+    export mlatom='{MLatom_py_file}'
+    $mlatom "$@"
+    """
+    with open(script_path, 'w') as f:
+        f.write(content)
+
+def chmod_py(path):
+    for py_file in Path(path).glob('*.py'):
+        py_file.chmod(0o755)
+
+class InstallScripts(install_scripts):
+    def run(self):
+        install_scripts.run(self)
+
+        # Rename some script files
+        for script in self.get_outputs():
+            if script.endswith('mlatom'):
+                modify_mlatom_script(script)
+
+here = os.path.abspath(os.path.dirname(__file__))
+with open(os.path.join(here, 'README.md')) as f:
+    README = f.read()
+
+setup(
+    name = pkg_name,
+    version = "3.0.0",
+    author = "Pavlo O. Dral",
+    author_email = "admin@mlatom.com",
+    license = 'MIT (modified)',
+    description = "A Package for Atomistic Simulations with Machine Learning",
+    long_description = README,
+    long_description_content_type = 'text/markdown',
+    url = "http://mlatom.com",
+    python_requires='>=3.8',
+    packages = find_packages('src'),
+    package_dir = {'' : 'src'},
+    # scripts = ['mlatom', 'MLatomF'],
+    package_data = {"": ['MLatomF', 'README', '*.json', 'cs.so', '*.cpp', '*.pt', '*.dat', '*.txt', '*.pkl', '*.inp', '*.f90', 'Makefile', 'Makefile.intel', '*.saved', '*.sh']},
+    classifiers = [
+        "Programming Language :: Python :: 3",
+        "Operating System :: POSIX :: Linux",
+        "Programming Language :: Fortran",
+        "Topic :: Scientific/Engineering :: Chemistry",
+        "Environment :: Console",
+    ],
+    install_requires = [],
+    # , 'pandas', '<scikit-learn> < <1.0.0>', 'xgboost', 'rdkit'
+    entry_points = {
+        'console_scripts' : ['mlatom-gui = mlatom.mlatom_gui:main',
+                             'mlatom_gui = mlatom.mlatom_gui:main',
+                             'mlatom = mlatom.shell_cmd:mlatom',
+                             # 'MLatom.py = MLatom.shell_cmd:mlatom',
+                             'MLatomF = mlatom.shell_cmd:MLatomF']
+    }
+    # cmdclass = {
+    #     "install_scripts": InstallScripts
+    # }
+)
+
+# bin_path = os.path.dirname(sys.executable)
+# modify_mlatom_script(os.path.join(bin_path, mlatom_script))
+# chmod_py(os.path.join(site_pkg, pkg_name))