# pyphotonics
PyPhotonics is a post-processing python code that calculates photonic properties of materials. Based on the outcome of DFT, constrained DFT and vibrational calculations using DFT performed using VASP for a defect system, PyPhotonics uses the results in the output files and calculates the Huang-Rhys factor of the defect and the photoluminescence line-shape. Soon, the code will calculate the carrier capture coefficient and carrier lifetimes for defects, which are essential quantities for assessing the photovoltaic efficiency of materials.
If you wish to use PyPhotonics, please cite our paper:
- [Sherif AbdulkaderTawfik, Salvy P.Russo, PyPhotonics: A python package for the evaluation of luminescence properties of defects, Computer Physics Communications, 2022, 273, 108222.](https://www.sciencedirect.com/science/article/pii/S0010465521003349)
# Installation
You can install PyPhotonics using the pip command: `pip install pyphotonics`. The following python packages are required:
- scipy
- numpy
- pandas
- matplotlib
- oganesson
# Directory structure
The `pyphotonics` module is composed of the following files:
```
/pyphotonics
/__init__.py
/constants.py: A list of physical constants.
/photoluminescence.py: Contains the Photoluminescence class, which drives the photonics calculations.
```
# How to use
## PL line-shape and the Huang-Rhys factor
To calculate the PL line-shape and the Huang-Rhys of a crystal structure using pyphotonics, a number of DFT calculations should be performed with VASP first:
- The ground state structure of the crystal should be optimized. Let's call the output file CONTCAR_GS.
- The excited state structure of the crystal should be optimized. Let's call the output file CONTCAR_ES. For a tutorial on how to setup such calculation, see this [tutorial](./vasp_constrained_occupations.md)
- The phonon modes of the ground state system should be calculated with VASP, and the `bands.yaml` file should be produced using the `phonopy` code.
Once all of the above is done, you can calculate the HR factor and PL line-shape as follows (the complete example is in the `test/` directory):
```
from pyphotonics.photoluminescence import Photoluminescence
p = Photoluminescence("CONTCAR_GS", "CONTCAR_ES", 189, method="phonopy", resolution=1000)
```
You can also run `pyphotonics` from the command line by typing the following in the directory `test/photoluminscence/`:
```
pyphotonics -cgs CONTCAR_GS -ces CONTCAR_ES -m 189 -M phonopy -r 1000
```
## Setting up the INCAR for CDFT
VASP allows you to excite a crystal structure by constraining the occupations of the electronic bands. Let's say you want to excite a spin-up (spin component 1) or spin-down (spin component 2) electron from the ground state to the excited state. To do this, run the following command:
```
pyphotonics-incar <path to your OUTCAR file>
```
`pyphotonics` will write to the terminal the values of the two INCAR tags, `FERWE` and `FERDO`, which you can then copy-paste into your INCAR file to perform the excited state optimisation.
There is a sample `OUTCAR` file in the directory `test/ferwe_ferdo` which you can test with. Go to the directory and type: `pyphotonics-incar`.
### What are the `FERWE` and `FERDO`?
These are INCAR tags that specify the electronic occupation. Here is how you can construct those tags for any structure:
- Find out how many bands do you have. You can obtain that by search for `NBANDS` in the OUTCAR file
- Find out how many k points do you have. You can look that up in the OUTCAR by searching for the section that starts with the string spin component 1 in the OUTCAR. Let's call that number `N_K`.
- Find out how many electrons are occupying spin components 1 and 2 by searching the **last** such section in the OUTCAR that starts with spin component 1. Let's say there are `O_UP` electrons that occupy the spin up, `O_DN` electrons that occupy the spin down.
- Next, calculate how many states are empty in both spins: empty states in the spin up = `U_UP` where `U_UP = NBANDS - O_UP`. Same applies for `U_DN`.
Finally, add the `FERWE` (spin up, or spin component 1) and `FERDO` (spin down, or spin component 2) as follows:
- `FERWE = [O_UP-1]*1.0 1*0.0 1*1.0 [U_UP-1]*0.0 <repeated N_K times>`
- `FERDO = [O_DN]*1.0 [U_DN]*0.0 <repeated N_K times>`
Note the `<repeated N_K times>` above. It means: repeat `[O_UP-1]*1.0 1*0.0 1*1.0 [U_UP-1]*0.0` for `N_K` times.
Let's have an example. Let's say we have 8 kpoints in both spins, 216 bands, where the spin up electrons occupy 144 bands and the spin down occupy 142 bands. Then, here are the two tags:
- `FERWE = 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0`
- `FERDO = 142*1.0 74*0.0 142*1.0 74*0.0 142*1.0 74*0.0 142*1.0 74*0.0 142*1.0 74*0.0 142*1.0 74*0.0 142*1.0 74*0.0 142*1.0 74*0.0`
Raw data
{
"_id": null,
"home_page": "https://github.com/sheriftawfikabbas/pyphotonics",
"name": "pyphotonics",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "DFT, Material science, Photoluminescence, VASP",
"author": "Sherif Abdulkader Tawfik",
"author_email": "sherif.tawfic@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/09/f1/0d7f03926260b07561cdca15b6e2c719d372764f247891153fdd911d5e25/pyphotonics-0.2.0.tar.gz",
"platform": null,
"description": "# pyphotonics\r\n\r\nPyPhotonics is a post-processing python code that calculates photonic properties of materials. Based on the outcome of DFT, constrained DFT and vibrational calculations using DFT performed using VASP for a defect system, PyPhotonics uses the results in the output files and calculates the Huang-Rhys factor of the defect and the photoluminescence line-shape. Soon, the code will calculate the carrier capture coefficient and carrier lifetimes for defects, which are essential quantities for assessing the photovoltaic efficiency of materials.\r\n\r\nIf you wish to use PyPhotonics, please cite our paper:\r\n\r\n- [Sherif AbdulkaderTawfik, Salvy P.Russo, PyPhotonics: A python package for the evaluation of luminescence properties of defects, Computer Physics Communications, 2022, 273, 108222.](https://www.sciencedirect.com/science/article/pii/S0010465521003349)\r\n\r\n\r\n# Installation\r\n\r\nYou can install PyPhotonics using the pip command: `pip install pyphotonics`. The following python packages are required:\r\n\r\n- scipy\r\n- numpy\r\n- pandas\r\n- matplotlib\r\n- oganesson\r\n\r\n# Directory structure\r\n\r\nThe `pyphotonics` module is composed of the following files:\r\n\r\n```\r\n/pyphotonics\r\n /__init__.py\r\n /constants.py: A list of physical constants.\r\n /photoluminescence.py: Contains the Photoluminescence class, which drives the photonics calculations.\r\n```\r\n\r\n# How to use\r\n\r\n## PL line-shape and the Huang-Rhys factor\r\n\r\nTo calculate the PL line-shape and the Huang-Rhys of a crystal structure using pyphotonics, a number of DFT calculations should be performed with VASP first:\r\n- The ground state structure of the crystal should be optimized. Let's call the output file CONTCAR_GS.\r\n- The excited state structure of the crystal should be optimized. Let's call the output file CONTCAR_ES. For a tutorial on how to setup such calculation, see this [tutorial](./vasp_constrained_occupations.md)\r\n- The phonon modes of the ground state system should be calculated with VASP, and the `bands.yaml` file should be produced using the `phonopy` code.\r\n\r\nOnce all of the above is done, you can calculate the HR factor and PL line-shape as follows (the complete example is in the `test/` directory):\r\n\r\n\r\n```\r\nfrom pyphotonics.photoluminescence import Photoluminescence\r\np = Photoluminescence(\"CONTCAR_GS\", \"CONTCAR_ES\", 189, method=\"phonopy\", resolution=1000)\r\n\r\n```\r\n\r\nYou can also run `pyphotonics` from the command line by typing the following in the directory `test/photoluminscence/`:\r\n\r\n```\r\npyphotonics -cgs CONTCAR_GS -ces CONTCAR_ES -m 189 -M phonopy -r 1000\r\n```\r\n\r\n\r\n## Setting up the INCAR for CDFT\r\n\r\nVASP allows you to excite a crystal structure by constraining the occupations of the electronic bands. Let's say you want to excite a spin-up (spin component 1) or spin-down (spin component 2) electron from the ground state to the excited state. To do this, run the following command:\r\n\r\n```\r\npyphotonics-incar <path to your OUTCAR file>\r\n```\r\n\r\n\r\n`pyphotonics` will write to the terminal the values of the two INCAR tags, `FERWE` and `FERDO`, which you can then copy-paste into your INCAR file to perform the excited state optimisation.\r\n\r\nThere is a sample `OUTCAR` file in the directory `test/ferwe_ferdo` which you can test with. Go to the directory and type: `pyphotonics-incar`.\r\n\r\n### What are the `FERWE` and `FERDO`?\r\n\r\nThese are INCAR tags that specify the electronic occupation. Here is how you can construct those tags for any structure:\r\n\r\n- Find out how many bands do you have. You can obtain that by search for `NBANDS` in the OUTCAR file\r\n- Find out how many k points do you have. You can look that up in the OUTCAR by searching for the section that starts with the string spin component 1 in the OUTCAR. Let's call that number `N_K`.\r\n- Find out how many electrons are occupying spin components 1 and 2 by searching the **last** such section in the OUTCAR that starts with spin component 1. Let's say there are `O_UP` electrons that occupy the spin up, `O_DN` electrons that occupy the spin down.\r\n- Next, calculate how many states are empty in both spins: empty states in the spin up = `U_UP` where `U_UP = NBANDS - O_UP`. Same applies for `U_DN`.\r\n\r\nFinally, add the `FERWE` (spin up, or spin component 1) and `FERDO` (spin down, or spin component 2) as follows:\r\n\r\n- `FERWE = [O_UP-1]*1.0 1*0.0 1*1.0 [U_UP-1]*0.0 <repeated N_K times>`\r\n- `FERDO = [O_DN]*1.0 [U_DN]*0.0 <repeated N_K times>`\r\n\r\nNote the `<repeated N_K times>` above. It means: repeat `[O_UP-1]*1.0 1*0.0 1*1.0 [U_UP-1]*0.0` for `N_K` times.\r\n\r\nLet's have an example. Let's say we have 8 kpoints in both spins, 216 bands, where the spin up electrons occupy 144 bands and the spin down occupy 142 bands. Then, here are the two tags:\r\n\r\n- `FERWE = 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0`\r\n- `FERDO = 142*1.0 74*0.0 142*1.0 74*0.0 142*1.0 74*0.0 142*1.0 74*0.0 142*1.0 74*0.0 142*1.0 74*0.0 142*1.0 74*0.0 142*1.0 74*0.0`\r\n\r\n",
"bugtrack_url": null,
"license": "gpl-3.0",
"summary": "The PyPhotonics python code is a post-processing code written entirely in python which takes as input the output files of the VASP and phonopy codes for a defect system, and calculates the Huang-Rhys factor and the PL lineshapes for that system.",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/sheriftawfikabbas/pyphotonics"
},
"split_keywords": [
"dft",
" material science",
" photoluminescence",
" vasp"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "78c6bbebc7019181aa743e1cb5cf23b66b0849e007e237ff7a8cac43e013fe8b",
"md5": "8c4f725ddf2d67b8010bfb55ba3ce1c5",
"sha256": "8505b1630f2c22449cbbf0b8005dff5855514df3ae3f1e8b93b58c91c29fc9c5"
},
"downloads": -1,
"filename": "pyphotonics-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8c4f725ddf2d67b8010bfb55ba3ce1c5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7986,
"upload_time": "2024-12-16T01:35:44",
"upload_time_iso_8601": "2024-12-16T01:35:44.514622Z",
"url": "https://files.pythonhosted.org/packages/78/c6/bbebc7019181aa743e1cb5cf23b66b0849e007e237ff7a8cac43e013fe8b/pyphotonics-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "09f10d7f03926260b07561cdca15b6e2c719d372764f247891153fdd911d5e25",
"md5": "b8fdd27634eba1600b990c15899282b7",
"sha256": "138aba55691e7d400992bed9f246e5a898a8e221b54b0428c405b0ecd3dacf27"
},
"downloads": -1,
"filename": "pyphotonics-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "b8fdd27634eba1600b990c15899282b7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9853,
"upload_time": "2024-12-16T01:35:47",
"upload_time_iso_8601": "2024-12-16T01:35:47.445259Z",
"url": "https://files.pythonhosted.org/packages/09/f1/0d7f03926260b07561cdca15b6e2c719d372764f247891153fdd911d5e25/pyphotonics-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-16 01:35:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sheriftawfikabbas",
"github_project": "pyphotonics",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyphotonics"
}
JSON
