search

materialsproject / atomate2

atomate2 is a library of computational materials science workflows
https://materialsproject.github.io/atomate2/
Other
169 stars 96 forks source link

Documentation Suggestions #11

Closed Andrew-S-Rosen closed 3 years ago

Andrew-S-Rosen commented 3 years ago

A Few Documentation Suggestions

I wanted to share a few comments below regarding the documentation. It's excellent! It strikes a great balance between being concise/clear and having enough information to get started easily. I did have a few suggestions after reading through it, which I've included below. Feel free to address as little or as much of this as you wish. They're merely my opinions.

  1. I know that one of the main philosophies of Atomate is that it abstracts away a lot of the DFT settings from the user, which is great. At the same time, I think it's important for the more "expert" users to easily see what's going on underneath-the-hood. For instance, while I gathered the StaticMaker ran a static calculation, it wasn't immediately clear to me what other settings were changed. Should I be updating ISMEAR, or has Atomate2 already done that for me? Does it output AECCAR files by default, or do I need to take care of that? Of course, going to the code for the StaticSetGenerator clarified that for me, but I'm wondering if it might be helpful to include a hyperlink (in the documentation for the various Makers) to the various updates Atomate2 automatically applies.
  2. The "modifying input parameters" section of the documentation is fantastic. I think a few things could be added though. Namely, it would probably be worth mentioning that it's not just the INCAR flags that can be changed. The k-points and POTCARs can be changed too. While all the input arguments to VaspInputSetGenerator() don't need to be repeated in the documentation, a brief mention that other settings can be changed may be helpful for the reader.
    • EDIT: I've drafted something for this.
  3. In the VaspInputSetGenerator documentation, I initially was very unsure what a config_dict was. After about 15 minutes of realizing "there must be a better way" to handle entirely new input sets than defining massive user_incar_settings, user_kpoints_settings, etc. arguments, I then learned what it was after digging through the code itself. Perhaps a link to the BaseVaspSet.yaml file (as an example) might be helpful. Or something of that nature.
    • EDIT: I've drafted something for this.
  4. When describing the user_incar_settings option in the "modifying input parameters" section of the tutorial, perhaps it might be beneficial to mention that setting None will remove the user INCAR setting. I was fortunate to stumble upon it in the documentation for VaspInputSetGenerator, but this might be something to add to the main documentation as a note.
    • Edit: This is perhaps too niche in hindsight.
  5. "The different input sets used in atomate2 mean total energies cannot be compared against energies taken from the Materials Project" is found in the documentation, which I think is important. Perhaps it might be good to add "by default" to the end or something. Of course, Atomate2 can be made compatible with MP. It's mostly a matter of using different input sets, which you have made really easy to do with the config_dict arguments. Just define your own .yaml file and away you go, for the most part.
    • EDIT: I've drafted something for this.
Andrew-S-Rosen commented 3 years ago

Addressed in #13.