 [](https://results.pre-commit.ci/latest/github/JaGeo/LobsterPy/main) [](https://codecov.io/gh/JaGeo/LobsterPy) [](https://jageo.github.io/LobsterPy/) [](https://badge.fury.io/py/lobsterpy) [](https://pypi.org/project/lobsterpy) [](https://pepy.tech/project/lobsterpy)  [](https://zenodo.org/badge/latestdoi/343384088) [](https://joss.theoj.org/papers/4e8524125e36486c65a4b435bbfe2df2)
# Getting started
<img src="https://raw.githubusercontent.com/JaGeo/LobsterPy/main/LobsterPyLogo.png" alt="LobsterPy Logo which consists of a green Python and a red Lobster" width="200"/>
LobsterPy is a package that enables automatic analysis of LOBSTER outputs to get summarized bonding information and relevant bond plots. Additionally, one can also generate features for machine learning studies from LOBSTER outputs. One can download LOBSTER from [http://www.cohp.de](http://www.cohp.de).
<div style="border: 1px solid #52a5ab; padding: 5px; position: relative;">
<div style="background-color: #52a5ab; color: #ffffff; padding: 0px; position: absolute; top: 0; left: 0; right: 0; text-align: center;">
<strong>Important</strong>
</div>
<br>
Recently released [LOBSTER 5.0](https://schmeling.ac.rwth-aachen.de/cohp/index.php?menuID=6) now generates `POSCAR.lobster` for any kind of LOBSTER calculation by default (This file has same format as the POSCAR from VASP). Thus, LobsterPy in principle, now supports usage with **all** DFT codes supported by LOBSTER and is **no** longer limited to `VASP`. Almost all of the core functionalities of LobsterPy could be used. The user must use `POSCAR.lobster` for `path_to_poscar` and `-fstruct` argument in python and cli interface, respectively.
The only functionality limited to VASP is DOS comparisons and basis set analysis in the `calc_quality_summary` method of the `Analysis` class, as it relies on VASP output files, namely `vasprun.xml` and `POTCAR`.
</div>
Please note that LobsterPy relies on the LOBSTER computation output files. Thus, it will be only able to analyze data that has been computed in the LOBSTER run.
## Installation
### Python version
Before the installation, please make sure that you are using one of the supported Python versions (see [pyproject.toml](https://github.com/JaGeo/LobsterPy/blob/main/pyproject.toml)).
### Standard installation
Install using ``pip install lobsterpy``
### Installation with featurizer
Install using ``pip install lobsterpy[featurizer]``
## Basic usage
* **Automatic analysis and plotting of COHPs / COBIS / COOPs:**
<img src="https://github.com/JaGeo/LobsterPy/assets/22094846/6587e752-6ea4-4358-a763-3633d5a21869" alt="Output Automatic Analysis" width="300"/>
You can use ``lobsterpy description`` for an automated analysis of COHPs for relevant cation-anion bonds or ``lobsterpy automatic-plot`` to plot the results automatically.
It will evaluate all COHPs with ICOHP values down to 10% of the strongest ICOHP.
You can enforce an analysis of all bonds by using ``lobsterpy automatic-plot --allbonds``.
You can also switch the automatic analysis to use the ICOBIs or ICOOPs. You need to add `--cobis` or `--coops` along with the mentioned commands
for e.g.like ``lobsterpy description --cobis``
An interactive plotter is available via ``lobsterpy automatic-plot-ia``.
Currently, the computed Mulliken charges will be used to determine cations and anions. If no ``CHARGE.lobster`` is available, the algorithm will fall back to the BondValence analysis from pymatgen.
*Please be aware that LobsterPy can only analyze bonds that have been included in the initial Lobster computation. Thus, please use the cohpgenerator within Lobster (i.e., put `cohpGenerator from 0.1 to 5.0` in the *lobsterin*).*
It is also possible to start this automatic analysis from a Python script. See "examples" for scripts.
* **Plotting DOS from LOBSTER computations:**
To plot densities of states obtained from LOBSTER use ``lobsterpy plot-dos``.
* **Generic COHP/ COOP / COBI plotter**:
We included options to plot COHPs/COBIs/COOPs from the command line.
``lobsterpy plot 1 2`` will plot COHPs of the first and second bond from ``COHPCAR.lobster``. It is possible to sum or integrate the COHPs as well (``--summed``, ``--integrated``). You can switch to COBIs or COOPs by using ``--cobis`` or ``--coops``, respectively.
* **Other command line tools**:
``lobsterpy create-inputs`` will create standard inputs based on existing POSCAR, POTCAR, and INCAR files. It will allow testing for different basis sets that are available in Lobster. This feature is currently only available for PBE_54 POTCARs, as only the pbeVASPfit2015 basis in LOBSTER that has been fitted to PBE POTCARs includes additional orbitals relevant to solid-state materials. Please
check out our publication [https://doi.org/10.1002/cplu.202200123](https://doi.org/10.1002/cplu.202200123) and LOBSTER program manual for more information
* **Further help?**
You can get further information by using ``lobsterpy --help`` and also by typing ``lobsterpy description --help``,
``lobsterpy automatic-plot --help``, ``lobsterpy plot --help``.
## Comprehensive documentation
* Checkout the [documentation and tutorials](https://jageo.github.io/LobsterPy/) for more details.
## Contributing
A short guide to contributing to LobsterPy can be found [here](https://jageo.github.io/LobsterPy/dev/contributing.html).
Additional information for developers can be found [here](https://jageo.github.io/LobsterPy/dev/dev_installation.html).
## How to cite?
Please cite our paper: A. A. Naik, K. Ueltzen, C. Ertural, A. J. Jackson, J. George, *Journal of Open Source Software* **2024**, *9*, 6286. [https://joss.theoj.org/papers/10.21105/joss.06286](https://joss.theoj.org/papers/10.21105/joss.06286).
Please cite [pymatgen](https://github.com/materialsproject/pymatgen), [Lobster](https://schmeling.ac.rwth-aachen.de/cohp/index.php?menuID=1), and [ChemEnv](https://doi.org/10.1107/S2052520620007994) correctly as well.
You can find more information on the methodology of the automatic analysis in J. George, G. Petretto, A. Naik, M. Esters, A. J. Jackson, R. Nelson, R. Dronskowski, G.-M. Rignanese, G. Hautier, *ChemPlusChem* **2022**, *87*, e202200123. [https://doi.org/10.1002/cplu.202200123](https://doi.org/10.1002/cplu.202200123).
## LobsterPy is now a part of an atomate2 workflow
We have now also included the automatic analysis into a fully automatic workflow using VASP and Lobster in [atomate2](https://github.com/materialsproject/atomate2). More documentation and information will follow soon.
## Acknowledgements
The development of the program has been supported by a computing time grant. We gratefully acknowledge the Gauss Centre for Supercomputing e.V. (www.gauss-centre.eu) for funding this project by providing computing time on the GCS Supercomputer SuperMUC-NG at Leibniz Supercomputing Centre (www.lrz.de) (project pn73da).
Raw data
{
"_id": null,
"home_page": null,
"name": "lobsterpy",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": null,
"keywords": "high-throughput, automated, lobsteroutput, bonding-analysis",
"author": null,
"author_email": "Janine George <janine.george@bam.de>",
"download_url": "https://files.pythonhosted.org/packages/34/b6/f52bcc98b0c31ec77b117ac063433b12f463981d1ce35208655081109f6e/lobsterpy-0.4.4.tar.gz",
"platform": null,
"description": " [](https://results.pre-commit.ci/latest/github/JaGeo/LobsterPy/main) [](https://codecov.io/gh/JaGeo/LobsterPy) [](https://jageo.github.io/LobsterPy/) [](https://badge.fury.io/py/lobsterpy) [](https://pypi.org/project/lobsterpy) [](https://pepy.tech/project/lobsterpy)  [](https://zenodo.org/badge/latestdoi/343384088) [](https://joss.theoj.org/papers/4e8524125e36486c65a4b435bbfe2df2)\n# Getting started\n<img src=\"https://raw.githubusercontent.com/JaGeo/LobsterPy/main/LobsterPyLogo.png\" alt=\"LobsterPy Logo which consists of a green Python and a red Lobster\" width=\"200\"/>\n\nLobsterPy is a package that enables automatic analysis of LOBSTER outputs to get summarized bonding information and relevant bond plots. Additionally, one can also generate features for machine learning studies from LOBSTER outputs. One can download LOBSTER from [http://www.cohp.de](http://www.cohp.de).\n\n<div style=\"border: 1px solid #52a5ab; padding: 5px; position: relative;\">\n <div style=\"background-color: #52a5ab; color: #ffffff; padding: 0px; position: absolute; top: 0; left: 0; right: 0; text-align: center;\">\n <strong>Important</strong>\n </div>\n<br>\n\nRecently released [LOBSTER 5.0](https://schmeling.ac.rwth-aachen.de/cohp/index.php?menuID=6) now generates `POSCAR.lobster` for any kind of LOBSTER calculation by default (This file has same format as the POSCAR from VASP). Thus, LobsterPy in principle, now supports usage with **all** DFT codes supported by LOBSTER and is **no** longer limited to `VASP`. Almost all of the core functionalities of LobsterPy could be used. The user must use `POSCAR.lobster` for `path_to_poscar` and `-fstruct` argument in python and cli interface, respectively.\n\nThe only functionality limited to VASP is DOS comparisons and basis set analysis in the `calc_quality_summary` method of the `Analysis` class, as it relies on VASP output files, namely `vasprun.xml` and `POTCAR`.\n</div>\n\nPlease note that LobsterPy relies on the LOBSTER computation output files. Thus, it will be only able to analyze data that has been computed in the LOBSTER run.\n\n\n\n\n## Installation\n\n### Python version\nBefore the installation, please make sure that you are using one of the supported Python versions (see [pyproject.toml](https://github.com/JaGeo/LobsterPy/blob/main/pyproject.toml)).\n\n### Standard installation\nInstall using ``pip install lobsterpy``\n\n### Installation with featurizer\nInstall using ``pip install lobsterpy[featurizer]``\n\n\n## Basic usage\n\n* **Automatic analysis and plotting of COHPs / COBIS / COOPs:**\n\n <img src=\"https://github.com/JaGeo/LobsterPy/assets/22094846/6587e752-6ea4-4358-a763-3633d5a21869\" alt=\"Output Automatic Analysis\" width=\"300\"/>\n\nYou can use ``lobsterpy description`` for an automated analysis of COHPs for relevant cation-anion bonds or ``lobsterpy automatic-plot`` to plot the results automatically.\nIt will evaluate all COHPs with ICOHP values down to 10% of the strongest ICOHP.\nYou can enforce an analysis of all bonds by using ``lobsterpy automatic-plot --allbonds``.\nYou can also switch the automatic analysis to use the ICOBIs or ICOOPs. You need to add `--cobis` or `--coops` along with the mentioned commands\nfor e.g.like ``lobsterpy description --cobis``\n\nAn interactive plotter is available via ``lobsterpy automatic-plot-ia``.\n\nCurrently, the computed Mulliken charges will be used to determine cations and anions. If no ``CHARGE.lobster`` is available, the algorithm will fall back to the BondValence analysis from pymatgen.\n\n*Please be aware that LobsterPy can only analyze bonds that have been included in the initial Lobster computation. Thus, please use the cohpgenerator within Lobster (i.e., put `cohpGenerator from 0.1 to 5.0` in the *lobsterin*).*\n\n\nIt is also possible to start this automatic analysis from a Python script. See \"examples\" for scripts.\n\n* **Plotting DOS from LOBSTER computations:**\n\n To plot densities of states obtained from LOBSTER use ``lobsterpy plot-dos``.\n\n\n* **Generic COHP/ COOP / COBI plotter**:\n\n We included options to plot COHPs/COBIs/COOPs from the command line.\n``lobsterpy plot 1 2`` will plot COHPs of the first and second bond from ``COHPCAR.lobster``. It is possible to sum or integrate the COHPs as well (``--summed``, ``--integrated``). You can switch to COBIs or COOPs by using ``--cobis`` or ``--coops``, respectively.\n\n* **Other command line tools**:\n\n ``lobsterpy create-inputs`` will create standard inputs based on existing POSCAR, POTCAR, and INCAR files. It will allow testing for different basis sets that are available in Lobster. This feature is currently only available for PBE_54 POTCARs, as only the pbeVASPfit2015 basis in LOBSTER that has been fitted to PBE POTCARs includes additional orbitals relevant to solid-state materials. Please\n check out our publication [https://doi.org/10.1002/cplu.202200123](https://doi.org/10.1002/cplu.202200123) and LOBSTER program manual for more information\n\n\n* **Further help?**\n\n You can get further information by using ``lobsterpy --help`` and also by typing ``lobsterpy description --help``,\n``lobsterpy automatic-plot --help``, ``lobsterpy plot --help``.\n\n## Comprehensive documentation\n* Checkout the [documentation and tutorials](https://jageo.github.io/LobsterPy/) for more details.\n\n## Contributing\nA short guide to contributing to LobsterPy can be found [here](https://jageo.github.io/LobsterPy/dev/contributing.html).\nAdditional information for developers can be found [here](https://jageo.github.io/LobsterPy/dev/dev_installation.html).\n\n## How to cite?\nPlease cite our paper: A. A. Naik, K. Ueltzen, C. Ertural, A. J. Jackson, J. George, *Journal of Open Source Software* **2024**, *9*, 6286. [https://joss.theoj.org/papers/10.21105/joss.06286](https://joss.theoj.org/papers/10.21105/joss.06286).\nPlease cite [pymatgen](https://github.com/materialsproject/pymatgen), [Lobster](https://schmeling.ac.rwth-aachen.de/cohp/index.php?menuID=1), and [ChemEnv](https://doi.org/10.1107/S2052520620007994) correctly as well.\n\nYou can find more information on the methodology of the automatic analysis in J. George, G. Petretto, A. Naik, M. Esters, A. J. Jackson, R. Nelson, R. Dronskowski, G.-M. Rignanese, G. Hautier, *ChemPlusChem* **2022**, *87*, e202200123. [https://doi.org/10.1002/cplu.202200123](https://doi.org/10.1002/cplu.202200123).\n\n## LobsterPy is now a part of an atomate2 workflow\n\n\nWe have now also included the automatic analysis into a fully automatic workflow using VASP and Lobster in [atomate2](https://github.com/materialsproject/atomate2). More documentation and information will follow soon.\n\n\n## Acknowledgements\nThe development of the program has been supported by a computing time grant. We gratefully acknowledge the Gauss Centre for Supercomputing e.V. (www.gauss-centre.eu) for funding this project by providing computing time on the GCS Supercomputer SuperMUC-NG at Leibniz Supercomputing Centre (www.lrz.de) (project pn73da).\n",
"bugtrack_url": null,
"license": "BSD 3-Clause",
"summary": "Package for automatic bonding analysis with Lobster/VASP",
"version": "0.4.4",
"project_urls": {
"changelog": "https://jageo.github.io/LobsterPy/about/changelog.html",
"documentation": "https://jageo.github.io/LobsterPy/",
"homepage": "https://jageo.github.io/LobsterPy/",
"repository": "https://github.com/JaGeo/LobsterPy"
},
"split_keywords": [
"high-throughput",
" automated",
" lobsteroutput",
" bonding-analysis"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eca58f3487c3a4ac203700e5cfa9327f8b48b4484453b00b4c51d4ac404c396e",
"md5": "2c864d03811f925b15cd04b055b3de17",
"sha256": "da0c6e8937f4e54f9feef842e6dcfac87aecfb87a335e1b0dfd03330fbef41ab"
},
"downloads": -1,
"filename": "lobsterpy-0.4.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2c864d03811f925b15cd04b055b3de17",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 66589,
"upload_time": "2024-05-02T17:42:37",
"upload_time_iso_8601": "2024-05-02T17:42:37.358172Z",
"url": "https://files.pythonhosted.org/packages/ec/a5/8f3487c3a4ac203700e5cfa9327f8b48b4484453b00b4c51d4ac404c396e/lobsterpy-0.4.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "34b6f52bcc98b0c31ec77b117ac063433b12f463981d1ce35208655081109f6e",
"md5": "b0a52c8d8fb12ece4a1d903e76566c79",
"sha256": "9f70e38b9cbec17b5eb275d2e423d5f3965dcab15bc7d0c58b894deeebe5729b"
},
"downloads": -1,
"filename": "lobsterpy-0.4.4.tar.gz",
"has_sig": false,
"md5_digest": "b0a52c8d8fb12ece4a1d903e76566c79",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 67037,
"upload_time": "2024-05-02T17:42:39",
"upload_time_iso_8601": "2024-05-02T17:42:39.251768Z",
"url": "https://files.pythonhosted.org/packages/34/b6/f52bcc98b0c31ec77b117ac063433b12f463981d1ce35208655081109f6e/lobsterpy-0.4.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-02 17:42:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JaGeo",
"github_project": "LobsterPy",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "lobsterpy"
}
JSON
