From 8a9f9921350d75f597e922f2c323c414896d288e Mon Sep 17 00:00:00 2001 From: "Dr. Sefer Bora Lisesivdin" Date: Tue, 4 Jul 2023 16:56:21 +0300 Subject: [PATCH] Update README.md --- README.md | 49 ++++++++++++++++++++++++------------------------- 1 file changed, 24 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index bd4f28f..b44c6da 100644 --- a/README.md +++ b/README.md @@ -9,17 +9,17 @@ ## Introduction *gpaw-tools* is a powerful and user-friendly UI/GUI tool for conducting Density Functional Theory (DFT) and molecular dynamics (MD) calculations. Our goal is to make DFT and MD calculations more accessible and easy to use for individuals and small groups, by providing a simple command-line interface and graphical user interface. -The *gpaw-tools* package is built on top of the ASE , ASAP3, KIM-API, PHONOPY and GPAW libraries, which are well-established and widely used in the scientific community. It allows users to simulate the properties of materials, optimize structures, investigate chemical reactions and processes, and perform calculations on systems with a large number of atoms. With gpaw-tools, researchers, students, and engineers in a wide range of fields, including materials science, chemistry, physics, and engineering, can easily conduct DFT and MD calculations and explore the electronic, optical and phonon structure of material systems. We are constantly working to improve and expand the capabilities of *gpaw-tools*, and we welcome feedback and contributions from the community. +The *gpaw-tools* package is built on top of the ASE, ASAP3, KIM-API, PHONOPY, and GPAW libraries, which are well-established and widely used in the scientific community. It allows users to simulate the properties of materials, optimize structures, investigate chemical reactions and processes, and perform calculations on systems with a large number of atoms. With gpaw-tools, researchers, students, and engineers in a wide range of fields, including materials science, chemistry, physics, and engineering, can easily conduct DFT and MD calculations and explore the electronic, optical and phonon structure of material systems. We are constantly working to improve and expand the capabilities of *gpaw-tools*, and we welcome feedback and contributions from the community. `gpaw-tools` have: -1. The main solver code `gpawsolver.py` which can be run in PW or LCAO mode. It can perform structure optimization, equation of state and elastic tensor calculations, use several different XCs (as well as hybrid XCs) for sspin-polarized DOS and band structure calculations, electron densities, phonon calculations and optical properties (RPA and BSE). In addition to calculations, it can draw DOS and band structures, save all data and figure in an ordered way. +1. The main solver code `gpawsolver.py` can run in PW or LCAO mode. It can perform structure optimization, equation of state and elastic tensor calculations, use several different XCs (as well as hybrid XCs) for spin-polarized DOS and band structure calculations, electron densities, phonon calculations, and optical properties (RPA and BSE). In addition to calculations, it can draw DOS and band structures, save all data and figure in an ordered way. 2. A force-field quick optimization script `asapsolve.py` for MD calculations using ASAP3 with OpenKIM potentials. -3. To choose better cut off energy, lattice parameter and k-points, there are 4 scripts called `optimize_cutoff.py`, `optimize_kpoints.py`, `optimize_kptsdensity.py` and `optimize_latticeparam.py`. +3. To choose better cut-off energy, lattice parameter, and k-points, there are 4 scripts called `optimize_cutoff.py`, `optimize_kpoints.py`, `optimize_kptsdensity.py`, and `optimize_latticeparam.py`. 4. A simple Graphical User Interface (GUI) for gpawsolve.py (and also you may say that GUI for GPAW) which is called `gg.py`. ## Usage ### Installation -You need to install many packages to run `gpaw-solve` successfully. Please refer to main [installation](https://www.lrgresearch.org/gpaw-tools/installation) web page for more. +You need to install many packages to run `gpaw-tools` successfully. Please refer to the main [installation](https://www.lrgresearch.org/gpaw-tools/installation) web page for more. ### gpawsolve.py This is the main code for easy and ordered PW/LCAO Calculations with ASE/GPAW. It can run as a command. @@ -30,19 +30,18 @@ Argument list: ``` -g, --geometry : Use a CIF file for geometry -i, --input : Use an input file for variables (input.py) If you do not use this argument, parameters - will be taken from the related lines of gpawsolve.py. Visit "Input File Keywords" webpage for more. --e, --energymeas : Energy consumption measurement. This feature only works with Intel CPUs after Sandy Bridge generation. - Results will be written in a file at results folder (as kWh!). + will be taken from the related lines of gpawsolve.py. Visit the "Input File Keywords" webpage for more. +-e, --energymeas : Energy consumption measurement. This feature only works with Intel CPUs after the Sandy Bridge generation. + Results will be written in a file in the results folder (as kWh!). -h, --help : Help --d, --drawfigures : Draws DOS and band structure figures at the end of calculation. --p, --passground : Passing ground calculations and continue with the next required calculation. --v, --version : Version information of running code and the latest stable code. Also gives download link. +-d, --drawfigures : Draws DOS and band structure figures at the end of the calculation. +-v, --version : Version information of running code and the latest stable code. Also gives a download link. ``` -Instead of using a geometry file, you can put an ASE Atoms object in to your input file for the geometry. As an example please note the example at: `examples\Bulk-aluminum` folder. +Instead of using a geometry file, you can put an ASE Atoms object into your input file for the geometry. As an example please note the example at: `examples\Bulk-GaAs-noCIF` folder. #### How to run? - Change `` with core numbers to use. For getting a maximum performance from your PC you can use `total number of cores - 1` or `total RAM/2Gb` as a ``. For CPUs supporting hyperthreading, users can use more than one instance of `gpawsolve.py` to achive maximum efficiency. + Change `` with core numbers to use. For getting maximum performance from your PC you can use `total number of cores - 1` or `total RAM/2Gb` as a ``. For CPUs supporting hyperthreading, users can use more than one instance of `gpawsolve.py` to achieve maximum efficiency. Usage: `$ mpirun -np gpawsolve.py ` @@ -59,21 +58,21 @@ or | PW | GLLBSC / M | No | Yes | Yes | Yes | Yes | No | Yes | Yes | Yes | | PW | HSE03, HSE06 | No | Yes | Yes | n/a | Yes | No | No | No | No | | PW-G0W0| Local and LibXC | No | No | Yes | No | No | No | Some | No | No | -| LCAO | Local and LibXC | No | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No | +| LCAO | Local and LibXC | No | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No | *: Just some ground state energy calculations. ### gg.py -Basic DFT calculations can be done graphically with the script `gg.py`. This script is behaving as a GUI to run `gpawsolve.py` script. To execute the GUI, type simply: +Basic DFT calculations can be done graphically with the script `gg.py`. This script behaves as a GUI to run `gpawsolve.py` script. To execute the GUI, type simply: `$ gg.py` ### asapsolve.py -Inter-atomic potentials are useful tool to perform a quick geometric optimization of the studied system before starting a precise DFT calculation. The `asapsolve.py` script is written for geometric optimizations with inter-atomic potentials. The bulk configuration of atoms can be provided by the user given as CIF file. A general potential is given for any calculation. However, user can provide the necessary OpenKIM potential by changing the related line in the input file. +The inter-atomic potential is a useful tool to perform a quick geometric optimization of the studied system before starting a precise DFT calculation. The `asapsolve.py` script is written for geometric optimizations with inter-atomic potentials. The bulk configuration of atoms can be provided by the user given as a CIF file. A general potential is given for any calculation. However, the user can provide the necessary OpenKIM potential by changing the related line in the input file. -Mainly, `asapsolve.py` is not related to GPAW. However it is dependent to ASAP3/OpenKIM and Kimpy. Therefore, the user must install necessary libraries before using the script. Please refer [related page](https://www.lrgresearch.org/gpaw-tools/installation/ubuntu/#installation-of-asap-and-kim-for-quick-optimization) for the installation needs. +Mainly, `asapsolve.py` is not related to GPAW. However, it is dependent on ASAP3/OpenKIM and Kimpy. Therefore, the user must install the necessary libraries before using the script. Please refer to [related page](https://www.lrgresearch.org/gpaw-tools/installation/ubuntu/#installation-of-asap-and-kim-for-quick-optimization) for the installation needs. -Main usage is: +The main usage is: `$ asapsolve.py ` @@ -87,18 +86,18 @@ Argument list: -i, --input : Use an input file for variables (input.py) -h --help : Help --v --version : Version information of running code and the latest stable code. Also gives download link. +-v --version : Version information of running code and the latest stable code. It also gives a download link. ``` ### optimizations/ciftoase.py -For `quickoptimize.py` or other optimization scripts, user may need to give ASE Atoms object instead of using a CIF file. This script changes a CIF file information to ASE Atoms object. Because there is a problem in the read method of ASE.io, sometimes it can give a double number of atoms. If the user lives this kind of problem, there is a setting inside the script. User can run the script like: +For `quickoptimize.py` or other optimization scripts, the user may need to give ASE Atoms object instead of using a CIF file. This script changes a CIF file information to ASE Atoms object. Because there is a problem in the read method of ASE.io, sometimes it can give a wrong number of atoms. If the user lives this kind of problem, there is a setting inside the script. Users can run the script like: python ciftoase.py -Result will be printed to screen and will be saved as `geometryfile.py` in the same folder. +The result will be printed on the screen and will be saved as `geometryfile.py` in the same folder. ### optimizations/optimize_cutoff (and kpoints)(and kptsdensity)(and latticeparam).py -Users must provide ASE Atoms object and simply insert the object inside these scripts. With the scripts, the user can do convergence tests for cut-off energy, k-points, k-point density and can calculate the energy dependent lattice parameter values. These codes are mainly based on Prof. J. Kortus, R. Wirnata's Electr. Structure & Properties of Solids course notes and GPAW's tutorials. Scripts can easily called with MPI as: +Users must provide an ASE Atoms object and simply insert the object inside these scripts. With the scripts, the user can do convergence tests for cut-off energy, k-points, and k-point density and can calculate the energy-dependent lattice parameter values. These codes are mainly based on Prof. J. Kortus, R. Wirnata's Electr. Structure & Properties of Solids course notes and GPAW's tutorials. Scripts can easily be called with MPI: gpaw -P python optimize_cutoff.py -- Structure.cif gpaw -P python optimize_kpoints.py -- Structure.cif @@ -108,19 +107,19 @@ Users must provide ASE Atoms object and simply insert the object inside these sc `optimize_latticeparam.py` can perform simultaneous calculation for lattice parameters a and c. And can also draw 3D contour graph for Energy versus lattice parameters (a and c). ### benchmarks/ -GPAW has many test scripts for many cases. However, new users may need something easy to run and compare. Some very easy single file test scripts will be listed [here](https://github.com/lrgresearch/gpaw-tools/tree/main/benchmarks) with some hardware benchmark information. Your timings are always welcomed. +GPAW has many test scripts for many cases. However, new users may need something easy to run and compare. Some very easy single-file test scripts will be listed [here](https://github.com/lrgresearch/gpaw-tools/tree/main/benchmarks) with some hardware benchmark information. Your timings are always welcome. ## examples/ There are [some example calculations](https://github.com/lrgresearch/gpaw-tools/tree/main/examples) given with different usage scenarios. Please send us more calculations to include in this folder. ## Input File Keywords -There are many keywords can be used in input files. You can find more at [here](https://www.lrgresearch.org/gpaw-tools/development/inputfilekeywords/) +There are many keywords that can be used in input files. You can find more at [here](https://www.lrgresearch.org/gpaw-tools/development/inputfilekeywords/) ## Release notes Release notes are listed at [here](https://www.lrgresearch.org/gpaw-tools/development/releasenotes/). ## Citing -Please do not forget that, gpaw-tools is a UI/GUI software. For the main DFT calculations, it uses ASE and GPAW. It also uses Elastic python package for elastic tensor solutions and ASAP with KIM database for interatomic interaction calculations. Therefore, you must know what you use, and cite them properly. Here, the basic citation information of each packages are given. +Please do not forget that gpaw-tools is a UI/GUI software. For the main DFT calculations, it uses ASE and GPAW. It also uses the Elastic python package for elastic tensor solutions and ASAP with the KIM database for interatomic interaction calculations and Phonopy for the phonon calculations. Therefore, you must know what you use, and cite them properly. Here, the basic citation information of each package is given. ### ASE * Ask Hjorth Larsen et al. "[The Atomic Simulation Environment—A Python library for working with atoms](https://doi.org/10.1088/1361-648X/aa680e)" J. Phys.: Condens. Matter Vol. 29 273002, 2017. @@ -137,7 +136,7 @@ And for `gpaw-tools` usage, please use the following citation: * S.B. Lisesivdin, B. Sarikavak-Lisesivdin "[gpaw-tools – higher-level user interaction scripts for GPAW calculations and interatomic potential based structure optimization](https://doi.org/10.1016/j.commatsci.2022.111201)" Comput. Mater. Sci. 204, 111201 (2022). -There are many other packages needed to be cited. With GPAW, you may needed to cite LibXC or cite for LCAO, TDDFT, lineer-response calculations. Please visit their pages for many other citation possibilities. For more you can visit [https://wiki.fysik.dtu.dk/ase/faq.html#how-should-i-cite-ase](https://wiki.fysik.dtu.dk/ase/faq.html#how-should-i-cite-ase), [https://wiki.fysik.dtu.dk/gpaw/faq.html#citation-how-should-i-cite-gpaw](https://wiki.fysik.dtu.dk/gpaw/faq.html#citation-how-should-i-cite-gpaw), and [https://openkim.org/how-to-cite/](https://openkim.org/how-to-cite/). +There are many other packages needed to be cited. With GPAW, you may need to cite LibXC or cite for LCAO, TDDFT, and linear-response calculations. Please visit their pages for many other citation possibilities. For more you can visit [https://wiki.fysik.dtu.dk/ase/faq.html#how-should-i-cite-ase](https://wiki.fysik.dtu.dk/ase/faq.html#how-should-i-cite-ase), [https://wiki.fysik.dtu.dk/gpaw/faq.html#citation-how-should-i-cite-gpaw](https://wiki.fysik.dtu.dk/gpaw/faq.html#citation-how-should-i-cite-gpaw), and [https://openkim.org/how-to-cite/](https://openkim.org/how-to-cite/). ## Licensing This project is licensed under the terms of the [MIT license](https://opensource.org/licenses/MIT).