From 9e327f0dcf20912c51c853b6d090d59748a54e30 Mon Sep 17 00:00:00 2001 From: emanuelm33 Date: Thu, 25 Aug 2022 18:14:36 +0200 Subject: [PATCH] readme file --- README.md | 169 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c1831f3 --- /dev/null +++ b/README.md @@ -0,0 +1,169 @@ +## BINPO: A CODE FOR ELECTRONIC PROPERTIES OF 2D ELECTRON SYSTEMS + +### Version 1.0 + +BinPo is a Python code to compute the electronic bandstructure and other properties in 2D electron +systems (2DES). At present, it could be used for electronic properties at the surface/interface of perovskite complex oxides, like strontium titanate (STO), in the main crystal faces. BinPo solves the Schrödinger-Poisson +scheme to obtain the self-consistent potential energy along the slab. The tight-binding Hamiltonian for this slab +is created from the transfer integrals in the Maximally Localized Wannier Functions (MLWF) basis. Once the self- +consistent (SC) solution is found, properties like projected bandstructure and Fermi surface, orbital decomposition +of electron density and envelope wavefunctions can be computed in post-processing steps. BinPo gives priority to +ease-of-use and efficiency in order to produce realistic simulations at low computational cost. High quality and +customized figures can be obtained from the simulations. To see details of the methodology applied, please refer to +our manuscript. To know how to use this code, please see "Usage" section below. + +### Prerequisites + +You will need to have installed a version 3.x of Python. If you don't have it, please, refer to the official Python +website https://www.python.org/. Along with Python 3.x you will need the following libraries: + +* NumPy >= 1.19 (https://numpy.org/) +* SciPy >= 1.5 (https://www.scipy.org/) +* Matplotlib >= 3.3 (https://matplotlib.org/) +* NumExpr >= 2.7 (https://numexpr.readthedocs.io/projects/NumExpr3/en/latest/) + +We recommend to install a Python scientific distribution like Anaconda (https://www.anaconda.com/) or another one, in +which the modules above mentioned are already included. Additionally, you will have to install the Atomic Simulation +Enviroment (ASE) library, version >= 3.2 (https://wiki.fysik.dtu.dk/ase/). + +### Features + +Currently, BinPo can be used for 2DES formed on the (100), (110) and (111) faces of: +* strontium titanate, STO +* potassium tantalate, KTO + +Additionally, the code has modularity to append new materials (cubic ABO3 perovskites) if desired. +BinPo allows for computing the following properties: +* The SC solution to the Schrödinger-Poisson scheme in the slab. It includes the SC-potential energy, electron density, + electric field and relative permittivity values. +* Bandstructure of the 2DES along high-symmetry points within the irreducible Brillouin zone. The bands calculation + can be total (without projections), projected onto the atomic orbitals or projected onto a set of planes. +* Fermi surface and, more generally, energy slices with or without projections onto the atomic orbitals. +* Decomposition of electron density into the atomic orbitals contributions. +* Envelope wavefunctions at gamma point calculation. +Furthermore, you can analyze the simulations results by Matplotlib interactive plots and generate customized high +quality plots for publishing. + +### License + +BinPo is Copyrighted by (C) 2021 BinPo Team. This code is distributed under the terms of the GNU General Public +License v3 (GPLv3), see ~/COPYING file or http://www.gnu.org/copyleft/gpl.txt. So that, you are free to use, modify, +improve and redistribute it. + +### Contact and help + +For reporting bugs or asking questions about the code, please write to the following email: emanuelm@ucm.es. +Request for adding features will be welcomed but without guarantees of future implementations. + +### What does each file/folder mean? + +* WFolder: This folder holds the initial Wannier90 output files (W90 files). These files come from a + DFT calculation + Wannier interpolation, and can be seen as the real space + Hamiltonian of the bulk unit cell. There is a specific file for each material, + as well as for the characteristics of the original DFT calculation (e. g. XC-functional). + +* examples: This folder contains .pdf files with detailed descriptions about the calculation presented as + examples in our main manuscript. + +* config_files: This folder contains the configuration files .yaml for each component of BinPo. Besides, there + is a "help_config.txt" file which explains the meaning of all parameters. + +* BP-preproc.py: Preprocessing component. It performs the tasks of filtering and rearrangement from the initial + Wannier files. + +* BPmodule.py: This file is the main module and contains classes, methods an attributes. + It is only called by others programs, the file itself does not need to be executed. + +* BPdatabase.py: This module contains a dictionary with the different materials and DFT treatments info. + For the time being, it contains the info for STO and KTO calculations. More data could be + added if the corresponding Wannier files are available. This file is not runnable, because + is imported by other programs and the information is obtained through the 'material' keyword. + +* BP-scp.py: Component for calculation of the SC potential energy along the slab (SC-potential). + Parameters not passed through the terminal are set by default from ~/conf_files/scp.yaml. + +* BP-fast_plot.py: Quick plotter for the output of "BP-scp.py". + +* BP-bands.py: Bandstructure calculator component. Bands calculation can include orbital character and/or bands + projections onto planes. You can pass the identifier for band calculation by terminal, and many + other parameters. Parameters not set will be taken from ~/conf_files/bands.yaml + +* BP-energy_slices.py: + Energy slices calculator component. The calculation includes orbital character. You can pass the + identifier for slice calculation by terminal, and many other parameters. Parameters not set will + be taken form ~/conf_files/energy_slices.yaml. At the end, the file is automatically saved for + plotting. + +* BP-energy_plot.py: + Energy slices plotter component. Plot the output of BP-energy_slices.py. Parameters not passed through + the terminal will be set by default from ~/conf_files/energy_plot.yaml. + +* BP-envelope_wfs.py: + Envelope wavefunctions calculator at gamma point. It allows for obtaining and visualizing the envelope + wavefunctions around the gamma point. Parameters not passed through the terminal will be set by default + from ~/conf_files/envelope_wfs.yaml. + +* BP-orb_density.py: + Orbital decomposition of electron density. It allows for decomposing and plotting the electron density + according to the orbital character. Parameters not passed through the terminal will be set by default + from ~/conf_files/orb_density.yaml. + +* COPYING.md: GPLv3 license file. + +* README.md: This file. + + +### Usage + +To see the usage and updatable parameters from command-line, please type: + $ python BP-component.py -h +where BP-component.py is any BinPo component. A list of the more frequently adjustable parameters will appear. +If a parameter is ommited, its value will be taken by default from the corresponding configuration file. + +In the following lines you will find a short description of how to use BinPo. For further details you can take a +look at ~/BPexamples folder. + +### STEP 1: pre-processing step: + +Run "BP-preproc.py". This component has two mandatory arguments: material (mt) and confinement direction (cfd). Choose the combination you want, +for example, STO and 111, as follows: + + $ python BP-preproc.py -mt STO -cfd 111 + +It will generate a folder, named as "Hr" + "material" + "direction", that holds the files corresponding to the rearrangment and +filtering of r-space Hamiltonian, discretized along normal direction according to the number of planes. You will find the folder + ~/HrSTO111 after a succesful pre-processing. + +NOTE: It should be noticed that you need to execute this step just once for each W90 file/material/direction combination. + +### STEP 2: SC-potential calculation: + +Run "BP-scp.py" component with a defined job identifier (id) as: + + $ python BP-scp.py -id identifier + +In this simplified example, many other parameters are being ignored. These will be taken from ~/conf_files/scp.yaml file. +The identifier will be unique for this calculation and can be recall later in any post-processing step. If the calculation converges +you will obtain an output folder holding the SC solution, a .log file and a .yaml file with a dictionary of parameters used in the +calculation. You can quickly check the output file by means of "BP-fast_plot.py" as: + + $ python BP-fast_plot.py -id identifier + +### STEP 3: post-processing step: + +NOTE: Each of the post-processing components needs a previous SC-potential calculation whose solution will be accessed by the specific +identifier. + +Recall the SC solutions and their features from any of the post-processing components (BP-bands.py, +BP-energy_slices.py, etc.). Check the parameters needed in each particular case. All new runs will be automatically logged in the +file ~/identifier/identifier.log. For example, to compute the bandstructure along KGK path (ph), run the line below. In this case, +the ommited parameters will be taken from ~/conf_files/bands.yaml file. + + $ python BP-bands.py -id identifier -ph KGK + +### Further information: + +* For learning about the differents option to edit plots (colors, colormaps, formats, etc.), check the Matplotlib documentation + at https://matplotlib.org/. +* For general information about .yaml files, visit https://yaml.org/. +