diff --git a/docs/conf.py b/docs/conf.py index 3334f4ac..8cfb8077 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -59,6 +59,8 @@ exclude_patterns = [ "test*.py", "test", + "paper", + "paper/*.md", "Thumbs.db", ".DS_Store", ] diff --git a/paper/paper.bib b/paper/paper.bib new file mode 100644 index 00000000..2414cb6c --- /dev/null +++ b/paper/paper.bib @@ -0,0 +1,172 @@ +@misc{atomate2, +title = {Atomate2}, +year = {2023}, +url = {https://github.com/materialsproject/atomate2} +} + +@article{ong2013python, + title={Python Materials Genomics (pymatgen): A robust, open-source python library for materials analysis}, + author={Ong, Shyue Ping and Richards, William Davidson and Jain, Anubhav and Hautier, Geoffroy and Kocher, Michael and Cholia, Shreyas and Gunter, Dan and Chevrier, Vincent L and Persson, Kristin A and Ceder, Gerbrand}, + journal={Computational Materials Science}, + volume={68}, + pages={314--319}, + year={2013}, + publisher={Elsevier}, + doi={10.1016/j.commatsci.2012.10.028}, +} + +@book{burdett1995chemical, + title={Chemical bonding in solids}, + author={Burdett, Jeremy K}, + year={1995}, + publisher={Oxford University Press} +} + +@article{dronskowski1993crystal, + title={Crystal orbital Hamilton populations (COHP): energy-resolved visualization of chemical bonding in solids based on density-functional calculations}, + author={Dronskowski, Richard and Bl{\"o}chl, Peter E}, + journal={The Journal of Physical Chemistry}, + volume={97}, + number={33}, + pages={8617--8624}, + year={1993}, + publisher={ACS Publications}, + doi={10.1021/j100135a014}, +} + +@book{dronskowski2023chemical, + title={Chemical Bonding: From Plane Waves via Atomic Orbitals}, + author={Dronskowski, Richard}, + year={2023}, + publisher={Walter de Gruyter GmbH \& Co KG}, + doi={10.1515/9783111167213}, +} + +@article{ngo2023dft, + title={DFT-Based Study for the Enhancement of CO2 Adsorption on Metal-Doped Nitrogen-Enriched Polytriazines}, + author={Ngo, Hieu Minh and Pal, Umapada and Kang, Young Soo and Ok, Kang Min}, + journal={ACS omega}, + volume={8}, + number={9}, + pages={8876--8884}, + year={2023}, + publisher={ACS Publications}, + doi={10.1021/acsomega.3c00395}, +} + +@article{naik2023quantumchemical, + title={A Quantum-Chemical Bonding Database for Solid-State Materials}, + author={Naik, Aakash Ashok, and Ertural, Christina, and Dhamrait, Nidal and Benner, Philipp and George, Janine}, + volume={10}, + issn={2052-4463}, + language={en}, + number={1}, + journal={Scientific Data}, + year={2023}, + pages={610}, + doi={10.1038/s41597-023-02477-5}, +} + +@article{das2023strong, + title={Strong Antibonding I (p)--Cu (d) States Lead to Intrinsically Low Thermal Conductivity in CuBiI4}, + author={Das, Anustoop and Pal, Koushik and Acharyya, Paribesh and Das, Subarna and Maji, Krishnendu and Biswas, Kanishka}, + journal={Journal of the American Chemical Society}, + volume={145}, + number={2}, + pages={1349--1358}, + year={2023}, + publisher={ACS Publications}, + doi={10.1021/jacs.2c11908}, +} + +@article{ertural2022first, + title={First-Principles Plane-Wave-Based Exploration of Cathode and Anode Materials for Li-and Na-Ion Batteries Involving Complex Nitrogen-Based Anions}, + author={Ertural, Christina and Stoffel, Ralf P and Mùˆller, Peter C and Vogt, C Alexander and Dronskowski, Richard}, + journal={Chemistry of Materials}, + volume={34}, + number={2}, + pages={652--668}, + year={2022}, + publisher={ACS Publications}, + doi={10.1021/acs.chemmater.1c03349}, +} + +@article{hoffmann1987chemistry, + title={How chemistry and physics meet in the solid state}, + author={Hoffmann, Roald}, + journal={Angewandte Chemie International Edition in English}, + volume={26}, + number={9}, + pages={846--878}, + year={1987}, + publisher={Wiley Online Library}, + doi={10.1002/anie.198708461}, +} + +@article{hu2023mechanism, + title={Mechanism of the low thermal conductivity in novel two-dimensional NaCuSe}, + author={Hu, Chengwei and Zhou, Lang and Hu, Xiaona and Lv, Bing and Gao, Zhibin}, + journal={Applied Surface Science}, + volume={613}, + pages={156064}, + year={2023}, + publisher={Elsevier}, + doi={10.1016/j.apsusc.2022.156064}, +} + +@article{hughbanks1983chains, + title={Chains of trans-edge-sharing molybdenum octahedra: metal-metal bonding in extended systems}, + author={Hughbanks, Timothy and Hoffmann, Roald}, + journal={Journal of the American Chemical Society}, + volume={105}, + number={11}, + pages={3528--3537}, + year={1983}, + publisher={ACS Publications}, + doi={10.1021/ja00349a027}, +} + +@article{mueller2021crystal, + title={Crystal orbital bond index: Covalent bond orders in solids}, + author={M\"uller, Peter C and Ertural, Christina and Hempelmann, Jan and Dronskowski, Richard}, + journal={The Journal of Physical Chemistry C}, + volume={125}, + number={14}, + pages={7959--7970}, + year={2021}, + publisher={ACS Publications}, + doi={10.1021/acs.jpcc.1c00718}, +} + +@article{george2022automated, + title={Automated Bonding Analysis with Crystal Orbital Hamilton Populations}, + author={George, Janine and Petretto, Guido and Naik, Aakash and Esters, Marco and Jackson, Adam J and Nelson, Ryky and Dronskowski, Richard and Rignanese, Gian-Marco and Hautier, Geoffroy}, + journal={ChemPlusChem}, + volume={87}, + number={11}, + pages={e202200123}, + year={2022}, + publisher={Wiley Online Library}, + doi={10.1002/cplu.202200123}, +} + +@article{chen2024insights, + title={Insights into the Heterogeneous Nuclei of an Ultrafast-Crystallizing Glassy Solid}, + author={Chen, Bin and Li, Junhua and Wang, Xu and Shi, Mengchao and Sun, Tulai and Xia, Mengjiao and Ding, Keyuan and Liu, Jie and Li, Jixue and Tian, He and others}, + journal={Advanced Functional Materials}, + pages={2314565}, + year={2024}, + publisher={Wiley Online Library}, + doi={10.1002/adfm.202314565}, +} + +@article{materialsproject, + title={Commentary: The Materials Project: A materials genome approach to accelerating materials innovation}, + author={Jain, Anubhav and Ong, Shyue Ping and Hautier, Geoffroy and Chen, Wei and Richards, William Davidson and Dacek, Stephen and Cholia, Shreyas and Gunter, Dan and Skinner, David and Ceder, Gerbrand and Persson, Kristin A}, + journal={APL materials}, + volume={1}, + number={1}, + year={2013}, + publisher={AIP Publishing}, + doi={10.1063/1.4812323}, +} diff --git a/paper/paper.md b/paper/paper.md new file mode 100644 index 00000000..bce7671a --- /dev/null +++ b/paper/paper.md @@ -0,0 +1,87 @@ +--- +title: 'LobsterPy: A package to automatically analyze LOBSTER runs' +tags: + - Python + - Automation + - Bonding analysis + - Machine learning +authors: + - name: Aakash Ashok Naik + orcid: 0000-0002-6071-6786 + affiliation: "1 , 2" + - name: Katharina Ueltzen + orcid: 0009-0003-2967-1182 + affiliation: 1 + - name: Christina Ertural + orcid: 0000-0002-7696-5824 + affiliation: 1 + - name: Adam J. Jackson + orcid: 0000-0001-5272-6530 + affiliation: 3 + - name: Janine George + orcid: 0000-0001-8907-0336 + affiliation: "1, 2" +affiliations: + - name: Federal Institute for Materials Research and Testing, Department Materials Chemistry, Berlin, 12205, Germany + index: 1 + - name: Friedrich Schiller University Jena, Institute of Condensed Matter Theory and Solid-State Optics, Jena, 07743, Germany + index: 2 + - name: Scientific Computing Department, Science and Technology Facilities Council, Rutherford Appleton Laboratory, Didcot, 0X11 0QX, UK + index: 3 +date: August 2023 +bibliography: paper.bib + +--- +# Summary +The LOBSTER software aids in extracting quantum-chemical bonding information from materials by projecting the +plane-wave based wave functions from density functional theory (DFT) onto an atomic orbital basis. [LobsterEnv](https://github.com/materialsproject/pymatgen/blob/master/pymatgen/io/lobster/lobsterenv.py), +a module implemented in pymatgen[@ong2013python] by some of the authors of this package, facilitates the use of quantum-chemical bonding +information obtained from LOBSTER calculations to identify neighbors and coordination environments. _LobsterPy_ is a Python package that offers a set of convenient tools +to further analyze and summarize the LobsterEnv outputs in the form of JSONs that are easy to interpret and process. These tools enable the +estimation of (anti) bonding contributions, generation of textual descriptions, and visualization of LOBSTER computation results. Since its first release, both _LobsterPy_ and _LobsterEnv_ capabilities +have been extended significantly. Unlike earlier versions, which could only automatically analyze Crystal Orbital Hamilton Populations (COHPs)[@dronskowski1993crystal], +both can now also analyze Crystal Orbital Overlap Populations (COOP)[@hughbanks1983chains] and Crystal Orbital Bond Index (COBI)[@mueller2021crystal]. +Extracting the information about the most important orbitals contributing to the bonds is optional, and users can enable it as needed. +Additionally, bonding-based features for machine-learning (ML) studies can be engineered via the sub-packages "featurize" and "structuregraphs". +Alongside its Python interface, it also provides an easy-to-use command line interface (CLI) that runs automatic analysis of the +computations and generates a summary of results and publication-ready figures. + +_LobsterPy_ has been used to produce the results in [@ngo2023dft; @chen2024insights; @naik2023quantumchemical] and is also part of +[@atomate2] bonding analysis workflow for generating bonding analysis data in a format compatible with the Materials Project[@materialsproject] API. + +# Statement of need +Although the notion of "bonds" might seem unusual from a physicist's point of view, chemists have been employing it routinely to +explain various chemical phenomena and materials properties.[@hoffmann1987chemistry; @burdett1995chemical; @das2023strong; @ertural2022first; @hu2023mechanism; @dronskowski2023chemical] With the recent advances in +automation frameworks for high-throughput computational investigations, bonding analysis for thousands of crystalline materials +can be performed with few lines of code.[@george2022automated] This automation helps reduce the common mistakes inexperienced +users make while performing bonding analysis. However, it is also essential to systematically generate inputs and post-process +the output files consistently to have reliable and reproducible results. Furthermore, transforming the data from these high-throughput +bonding analysis calculations into a format suitable for ML studies should benefit data-driven material science research. +_LobsterPy_ aims to fulfill this need. + +# Features +- Generate summarized bonding analysis JSONs and text descriptions based on COHPs (ICOHPs), COBIs (ICOBIs), and COOPs (ICOOPs) +- Generate static and interactive plots of the most relevant COHPs, COBIs, and COOPs +- Customizable plotters for visualization of COHPs (ICOHPs), COBIs (ICOBIs), COOPs (ICOOPs) and DOS +- Benchmark LOBSTER calculation quality and generate corresponding JSONs and text descriptions +- Create inputs for LOBSTER calculations from VASP files +- Extract features from LOBSTER calculation files to be used for ML studies +- Perform automatic bonding analysis and plotting via inherent command line interface app. + +# Availability +_LobsterPy_ can also be found on [PyPI](https://pypi.org/project/lobsterpy/). Detailed software documentation, +including [installation instructions](https://jageo.github.io/LobsterPy/installation/index.html) and +[implementation details](https://jageo.github.io/LobsterPy/fundamentals/index.html) are provided. The package +also includes [tutorials](https://jageo.github.io/LobsterPy/tutorial/index.html) illustrating all the basic and +advanced functionalities. + +# Acknowledgements +The authors would like to acknowledge the Gauss Centre for Super +computing e.V. (www.gauss-centre.eu) for funding this project by +providing generous computing time on the GCS Supercomputer +SuperMUC-NG at Leibniz Supercomputing Centre (www.lrz.de) +(project pn73da) that enabled rigorous testing of this +package on a diverse set of compounds. The authors thank Jonas Grandel for reviewing the docstrings and testing package functionalities +and tutorials. The authors would also like to acknowledge the maintainers of pymatgen and LOBSTER program developers. + +# References diff --git a/pyproject.toml b/pyproject.toml index 33074e68..1cd7d1a6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,6 +5,10 @@ requires = [ ] build-backend = "setuptools.build_meta" +[tool.setuptools.packages.find] +include = ["lobsterpy*"] +exclude = ["docs*", "tests*", "paper*"] + [project] name = "lobsterpy" description = "Package for automatic bonding analysis with Lobster/VASP"