| Name | abvio JSON |
| Version |
0.0.1
JSON |
| download |
| home_page | None |
| Summary | A Python package to simplify VASP input files |
| upload_time | 2024-08-01 19:30:14 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Abvio Repository
One of the things that I have always bemoaned is how bad input files are. But oh my god. I understand now that an input file with consistent and succinct syntax is so incredibly difficult to make. Rigidity and asking the user to learn how to write input files is far better than trying to anticipate all of the possibilities. If you are trying to add flexibility in an input file, it leads to unintended consequences that the user might be unaware of. Additionally, if there is more than one way to do something, then it becomes far too confusing (cough cough QuantumEspresso)
Conversely, rigidity does not allow for users to solve new problems that the developer hasn't considered before. If an input file does not allow abstraction or flexibility, then the user is confined to the conventions that you have thrust upon them.
Furthermore, rigid input files do not entirely solve the problem of unintended consequences. Specifically, if the program does not warn the user of unrecognized input tags, then that value is set to the default setting. I know this can be boiled down to "skill issue" or "bad software design", but there can be nefarious consequences to even long time users!
One example I can provide is that I had been blissfully unaware of a misspelling in my INCAR file. No warning or strange behavior had come of it. A sample of my input file is the following
```
EDIFF = 1e-06
EDIFFG = -0.01
NSW = 100
NELM = 30
IBRION = 2
ENCUT = 600
IDVW = 11
LWAVE = False
LAECHG = True
```
This file will run a perfectly fine VASP calculation with no warnings. But when life gives you melons, you might have misspelled an INCAR tag. In particular, `IVDW` is a totally, absolutely fine abbreviation. Especially as a chemist I should be trained to recognize the short hand for van der Waals. But as an _American_, I must pin this on the developers as a silly thing to let slide.
In my angst (and also Covid quaruntine), I decided to take up a challenge of writing a better input file for VASP calculations. In doing so, I have created the aptly named `abvio` (a better VASP input and output) python package. Developing this project was metaphorical and actual fever dream. You might notice this in some of the hastily written doc strings and naming conventions. Thankfully, the abvio package comes with comprehensive tests so hopefully that will allow me (or someone who is foolish enough to make a PR) to polish the codebase up in a reasonable time frame.
___
What I attempted to do is take a well understood data structure that provides both flexibility and convention and adorn in with ab initio jargon. This provides a few enormous benefits. One such benefit is that the foundation of your input file is well documented, tested, and understood by a wide audience.
Specifically, I have chosen to use a yaml file. Although, it is less familiar to people than perhaps json or csv, yaml is quick to learn and easy to read (mostly).
The following is an example of what a spin-orbit coupled band structure calculation of fluorite looks like
```yaml
structure:
mode: manual
species:
Ca: 4
F: 8
lattice:
a: 5.516052
b: 5.516052
c: 5.516052
alpha: 90.0
beta: 90.0
gamma: 90.0
coords: [
[0.0, 0.0, 0.0],
[0.0, 2.758, 2.758],
[2.758, 0.0, 2.758],
[2.758, 2.758, 0.0],
[1.379, 4.137, 1.379],
[1.379, 4.137, 4.137],
[1.379, 1.379, 4.137],
[1.379, 1.379, 1.379],
[4.137, 4.137, 4.137],
[4.137, 4.137, 1.379],
[4.137, 1.379, 1.379],
[4.137, 1.379, 4.137],
]
incar:
ediff: 1e-6
encut: 500
nelm: 35
ibrion: 2
lsorbit: true
lorbit: 11
magmom:
Ca: [0, 0, 1.0]
F: [0, 0, 0]
kpoints:
mode: autoline
spacing: 30
```
Currently, I am still unsure if this is aesthetically or functionally better than any other input file. Maybe let me know what you think.
What is nice about this format is that everything is in one place. You can understand the relation of your structure and what the program will do with it. For example, MAGMOM is no longer a mess of arithemtic. You can specify by species and provide an array of the spin-axes. Also, abvio can intelligently determine the band structure path of the input structure. All you have to do is specify the number of kpoints per path.
If these options aren't what you want, this input file supports all modes of kpoints generation.
What makes this easier to understand is that the methods are flexible, but the user must be aware of _state_. In this case, the `mode` parameter handles instances where state can change. This ensures that both the program and the user understand which method will be used to construct the structure and reciprocal space sampling scheme.
An even more terse inputs file can be used to demonstrate the convenience of this input file structure.
The following file does exactly the same as the previous, but in this case all we need to do is pass the canonical name of a specific structure type and the species that will fill the distinct sites. We then only need to pass modifications to the lattice parameter.
```yaml
structure:
mode: prototype
prototype: fluorite
species: [Ca, F]
lattice:
a: 5.516052
incar:
ediff: 1e-6
encut: 500
nelm: 35
ibrion: 2
lsorbit: true
lorbit: 11
magmom:
Ca: [0, 0, 1.0]
F: [0, 0, 0]
kpoints:
mode: autoline
spacing: 30
```
Finally, if we are feeling even lazier, we can pull structures from materials project directly (so long as you have an API key).
```yaml
structure:
mode: external
code: mp-2741
incar:
ediff: 1e-6
encut: 500
nelm: 35
ibrion: 2
lsorbit: true
lorbit: 11
magmom:
Ca: [0, 0, 1.0]
F: [0, 0, 0]
kpoints:
mode: autoline
spacing: 30
```
Each of these files will create the same set of VASP input files (you can check the tests to see if I am telling the truth!).
___
Input files, much like young grad students, need validation. In fact, I don't quite understand why some ab initio suites don't do some form of sanity check and just lets the calculations crash. Once again, yes due diligence of the user is paramount. But hey, sometimes people make mistakes.
So, I have attempted to bake sanity checks, input validation, and some wisdom into the processing of the input file. If you end up using this code, many warnings (and possibly errors) will be brought to the users attention even before the calculation has started. This might prevent a millisecond long disaster on week-long slurm queues.
___
If you want to try it out, feel free to take any of the above files and test them using the command line interface by running
```
abvio input.yaml -o /tmp
```
Which will write INCAR, KPOINTS, and POSCAR to the root tmp directory (just make sure you change the file name in the command to match your file name).
You can also preview what the output should look like using
```
abvio input.yaml --preview
```
Which will give an output like this
Raw data
{
"_id": null,
"home_page": null,
"name": "abvio",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "William Laderer <wtladerer@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/59/cc/78a02aee06cfb0fe0d6287339fccd5cfea2c63604a8f8c8bdcab08226e0e/abvio-0.0.1.tar.gz",
"platform": null,
"description": "# Abvio Repository\n\nOne of the things that I have always bemoaned is how bad input files are. But oh my god. I understand now that an input file with consistent and succinct syntax is so incredibly difficult to make. Rigidity and asking the user to learn how to write input files is far better than trying to anticipate all of the possibilities. If you are trying to add flexibility in an input file, it leads to unintended consequences that the user might be unaware of. Additionally, if there is more than one way to do something, then it becomes far too confusing (cough cough QuantumEspresso) \n\nConversely, rigidity does not allow for users to solve new problems that the developer hasn't considered before. If an input file does not allow abstraction or flexibility, then the user is confined to the conventions that you have thrust upon them. \n\nFurthermore, rigid input files do not entirely solve the problem of unintended consequences. Specifically, if the program does not warn the user of unrecognized input tags, then that value is set to the default setting. I know this can be boiled down to \"skill issue\" or \"bad software design\", but there can be nefarious consequences to even long time users! \n\nOne example I can provide is that I had been blissfully unaware of a misspelling in my INCAR file. No warning or strange behavior had come of it. A sample of my input file is the following\n\n```\nEDIFF = 1e-06\nEDIFFG = -0.01\nNSW = 100\nNELM = 30\nIBRION = 2\nENCUT = 600\nIDVW = 11\nLWAVE = False\nLAECHG = True\n```\n\nThis file will run a perfectly fine VASP calculation with no warnings. But when life gives you melons, you might have misspelled an INCAR tag. In particular, `IVDW` is a totally, absolutely fine abbreviation. Especially as a chemist I should be trained to recognize the short hand for van der Waals. But as an _American_, I must pin this on the developers as a silly thing to let slide.\n\nIn my angst (and also Covid quaruntine), I decided to take up a challenge of writing a better input file for VASP calculations. In doing so, I have created the aptly named `abvio` (a better VASP input and output) python package. Developing this project was metaphorical and actual fever dream. You might notice this in some of the hastily written doc strings and naming conventions. Thankfully, the abvio package comes with comprehensive tests so hopefully that will allow me (or someone who is foolish enough to make a PR) to polish the codebase up in a reasonable time frame. \n\n___\n\nWhat I attempted to do is take a well understood data structure that provides both flexibility and convention and adorn in with ab initio jargon. This provides a few enormous benefits. One such benefit is that the foundation of your input file is well documented, tested, and understood by a wide audience. \n\nSpecifically, I have chosen to use a yaml file. Although, it is less familiar to people than perhaps json or csv, yaml is quick to learn and easy to read (mostly).\n\nThe following is an example of what a spin-orbit coupled band structure calculation of fluorite looks like\n\n```yaml\n\nstructure:\n mode: manual\n species: \n Ca: 4\n F: 8\n lattice:\n a: 5.516052\n b: 5.516052\n c: 5.516052\n alpha: 90.0\n beta: 90.0\n gamma: 90.0\n coords: [\n [0.0, 0.0, 0.0],\n [0.0, 2.758, 2.758],\n [2.758, 0.0, 2.758],\n [2.758, 2.758, 0.0],\n [1.379, 4.137, 1.379],\n [1.379, 4.137, 4.137],\n [1.379, 1.379, 4.137],\n [1.379, 1.379, 1.379],\n [4.137, 4.137, 4.137],\n [4.137, 4.137, 1.379],\n [4.137, 1.379, 1.379],\n [4.137, 1.379, 4.137],\n ]\nincar:\n ediff: 1e-6\n encut: 500\n nelm: 35\n ibrion: 2\n lsorbit: true\n lorbit: 11\n magmom:\n Ca: [0, 0, 1.0]\n F: [0, 0, 0]\nkpoints:\n mode: autoline\n spacing: 30\n\n```\n\nCurrently, I am still unsure if this is aesthetically or functionally better than any other input file. Maybe let me know what you think. \n\nWhat is nice about this format is that everything is in one place. You can understand the relation of your structure and what the program will do with it. For example, MAGMOM is no longer a mess of arithemtic. You can specify by species and provide an array of the spin-axes. Also, abvio can intelligently determine the band structure path of the input structure. All you have to do is specify the number of kpoints per path. \n\nIf these options aren't what you want, this input file supports all modes of kpoints generation. \n\nWhat makes this easier to understand is that the methods are flexible, but the user must be aware of _state_. In this case, the `mode` parameter handles instances where state can change. This ensures that both the program and the user understand which method will be used to construct the structure and reciprocal space sampling scheme.\n\nAn even more terse inputs file can be used to demonstrate the convenience of this input file structure.\n\nThe following file does exactly the same as the previous, but in this case all we need to do is pass the canonical name of a specific structure type and the species that will fill the distinct sites. We then only need to pass modifications to the lattice parameter.\n\n```yaml\nstructure:\n mode: prototype\n prototype: fluorite\n species: [Ca, F]\n lattice:\n a: 5.516052\nincar:\n ediff: 1e-6\n encut: 500\n nelm: 35\n ibrion: 2\n lsorbit: true\n lorbit: 11\n magmom:\n Ca: [0, 0, 1.0]\n F: [0, 0, 0]\nkpoints:\n mode: autoline\n spacing: 30\n```\n\nFinally, if we are feeling even lazier, we can pull structures from materials project directly (so long as you have an API key).\n\n\n```yaml\nstructure:\n mode: external\n code: mp-2741\nincar:\n ediff: 1e-6\n encut: 500\n nelm: 35\n ibrion: 2\n lsorbit: true\n lorbit: 11\n magmom:\n Ca: [0, 0, 1.0]\n F: [0, 0, 0]\nkpoints:\n mode: autoline\n spacing: 30\n```\n\nEach of these files will create the same set of VASP input files (you can check the tests to see if I am telling the truth!). \n\n___\n\nInput files, much like young grad students, need validation. In fact, I don't quite understand why some ab initio suites don't do some form of sanity check and just lets the calculations crash. Once again, yes due diligence of the user is paramount. But hey, sometimes people make mistakes. \n\nSo, I have attempted to bake sanity checks, input validation, and some wisdom into the processing of the input file. If you end up using this code, many warnings (and possibly errors) will be brought to the users attention even before the calculation has started. This might prevent a millisecond long disaster on week-long slurm queues. \n\n___\n\nIf you want to try it out, feel free to take any of the above files and test them using the command line interface by running\n\n```\nabvio input.yaml -o /tmp\n```\n\nWhich will write INCAR, KPOINTS, and POSCAR to the root tmp directory (just make sure you change the file name in the command to match your file name). \n\nYou can also preview what the output should look like using \n\n```\nabvio input.yaml --preview\n```\n\nWhich will give an output like this\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python package to simplify VASP input files",
"version": "0.0.1",
"project_urls": {
"Documentation": "https://wladerer.github.io/abvio/",
"Issues": "https://github.com/wladerer/abvio/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "08ba45ba2aefad5a9a5d019048153ea5fe816436360595d1a822216dd39a561e",
"md5": "970f6a6e79ade2609d13f8d8a74effec",
"sha256": "7e8471c2e1e8d397c16604bae0b68e17d3a21ca9c667bc0ed9448315f4117bcf"
},
"downloads": -1,
"filename": "abvio-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "970f6a6e79ade2609d13f8d8a74effec",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 17016,
"upload_time": "2024-08-01T19:30:13",
"upload_time_iso_8601": "2024-08-01T19:30:13.019343Z",
"url": "https://files.pythonhosted.org/packages/08/ba/45ba2aefad5a9a5d019048153ea5fe816436360595d1a822216dd39a561e/abvio-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "59cc78a02aee06cfb0fe0d6287339fccd5cfea2c63604a8f8c8bdcab08226e0e",
"md5": "59fd2c8cb22a3b91f6cfd66014ed1853",
"sha256": "0d41cb8b79355c8eaf7686000e4efbbee924a176245e069ec63db209824c9d8e"
},
"downloads": -1,
"filename": "abvio-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "59fd2c8cb22a3b91f6cfd66014ed1853",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 23843,
"upload_time": "2024-08-01T19:30:14",
"upload_time_iso_8601": "2024-08-01T19:30:14.859905Z",
"url": "https://files.pythonhosted.org/packages/59/cc/78a02aee06cfb0fe0d6287339fccd5cfea2c63604a8f8c8bdcab08226e0e/abvio-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-01 19:30:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wladerer",
"github_project": "abvio",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "abvio"
}
