.. pyabst_doc documentation master file, created by sphinx-quickstart on Mon Jul 3 17:03:13 2017. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. .. toctree:: :maxdepth: 1 :caption: Contents: =========== PyAbstantia =========== About ===== PyAbstantia is a Python-based program for bond-valence sum (BVS) mapping and bond-valence energy landscape (BVEL). The author is `Shin-ichi NISHIMURA `_. Similar softwares are already available: * 3DBVSMAPPER_ * Bond_Str_ * `BVS Mapping`_ PyAbstantia is designed to visualize the ion diffusion pathways in two ways: 1. BVS (including softness-sensitive BVS) 2. BVEL BVS mode -------- In this mode, PyAbstantia outputs a three-dimensional map of deviations from the ideal valence of the target ion: .. math:: |\Delta V| = | V_{\rm target} - V_{\rm ideal} | BVEL mode --------- For details of BVEL, read `the review `_ and papers by `Prof. Stefan Adams `_. Changelog --------- * Jul. 21, 2017: Version 0.7b. ``build_lib.sh`` was modified for compiling with ifort on macOS. * Jul. 21, 2017: Version 0.7a. The gfortran compiler options in ``build_lib.sh`` was fixed. * Jul. 15, 2017: Version 0.7. This is the first public release of PyAbstantia. Installation ============ PyAbstantia is mainly written in Python_. The latest version (0.7) has been tested on Python 3.6.x and Python 2.7.x. The NumPy_ modules are required. Core parts of the map calculation are written in Fortran. Download -------- Download from `here `_. Install ------- 1. Expand the archive :: $ tar xvfj PyAbstantia-0.7a.tar.bz2 $ cd PyAbstantia-0.7a/ 2. Compile Fortran modules :: $ ./build_lib.sh 3. Make a symbolic link to the main program :: $ ln -s [WHERE_YOU_EXPANDED]/PyAbstantia-0.7/pyabst.py [ACTIVE_PATH]/pyabst Intel Compiler -------------- If you need more speed, you can use `Intel Fortran Compiler `_ (ifort) for compiling the core modules written in Fortran. To use the ifort, edit the following part of ``build_lib.sh``: :: FC=gfortran as :: FC=ifort How to Use ========== Run in terminal: :: $ pyabst [OPTIONS] [INPUT_FILE] Simply: :: $ pyabst sample.inp This execution outputs a binary file ``sample.pgrid`` for visualizing with VESTA_. Options ------- * ``-mp [NP]`` Enable multiprocessing. ``[NP]`` is a number of processes. * ``-t`` Output the 3D-map data in the ASCII format. (\*.grd format) For example: :: $ pyabst -mp 4 -t input.inp Input File ---------- PyAbstantia requires a input file storing the atomic coordinates information and the parameters relating to BVS. The input file is written in ASCII format. Lines starting with ``#`` are treated as comments. Arbitral numbers of blank lines are allowed. .. Note:: PyAbstantia does not use any symmetry operations. You have to supply all of the atomic coordinates in the unit cell. Use CIF mode for automatic generation of the input file. RIETAN-FP_ and its associated environment may help to generate the input file and to run the map calculation. Example: BVS mode ^^^^^^^^^^^^^^^^^ :: # alpha-AgI.inp # Title alpha-AgI # Lattice constants a, b, c, alpha, beta, gamma 5.06 5.06 5.06 90.0 90.0 90.0 # Formal valence of the target ion Ag^+ 1.0 # Number of counter ion species 1 # Symbol of the counter ion and bond valence parameters, R_0 and b I 2.38 0.37 # Resolution 50 50 50 # Atomic symbol, fractional coordinates and occupancy I 0.0 0.0 0.0 1.0 I 0.5 0.5 0.5 1.0 After running PyAbstantia, open the output file ``alpha-AgI.pgrid`` by VESTA_. Then: * Set the isosurface level to 0.4. * Deactivate the "Show Sections". .. image:: ./images/alpha-AgI_BVS_VESTA01.jpg You can visualize the BVS isosurface with the crystal structure by importing the \*.pgrid file to the crystal structural data. The purple spheres are the iodide ions. The isosurface is drawn at a BVS mismatch level of 0.2 for the silver ion Ag\ :sup:`+`\ . .. image:: ./images/alpha-AgI_BVS_VESTA02.jpg Example: BVEL mode ^^^^^^^^^^^^^^^^^^^ For BVEL mode, a keyword ``BVEL`` should be given at the end of title. This keyword activates an internal flag for BVEL. :: # LiMn2O4_HT_BVEL.inp # Title LiMn2O4_HT BVEL # Lattice constants 8.2483 8.2483 8.2483 90.0 90.0 90.0 # Target ion Li # Formal Charge 1.0 # Covalent radius 1.33 # Number of ion species 3 # Formal Charge 1.0 3.5 -2.0 # D_0 0.0 0.0 0.98816 # R_min 0.0 0.0 1.94001 # alpha 0.0 0.0 1.937984 # Covalent radius 1.33 1.61 0.66 # Resolution 82 82 82 # Atomic symbol, fractional coordinates and occupancy Li 0.12500 0.12500 0.12500 1.000 Li 0.12500 0.62500 0.62500 1.000 Li 0.62500 0.12500 0.62500 1.000 Li 0.62500 0.62500 0.12500 1.000 Li 0.87500 0.87500 0.87500 1.000 Li 0.87500 0.37500 0.37500 1.000 Li 0.37500 0.87500 0.37500 1.000 Li 0.37500 0.37500 0.87500 1.000 Mn 0.50000 0.50000 0.50000 1.000 Mn 0.50000 0.00000 0.00000 1.000 . . . Run from CIF ------------ PyAbstantia can read the Crystallographic Information File (CIF) as input data of crystal structure. This mode helps users to generate the standard input files via step by step prompts. This mode is implemented by using a CIF parser in pymatgen_. Install pymatgen_ to use CIFs as inputs. :: $ pyabst [OPTIONS] sample.CIF Following options are available only in the CIF mode. * ``-a`` Set the "softness-sensitive" parameters for the bond-valence calculation automatically. * ``-r [STEP]`` Set resolution automatically with resolution ``[STEP]`` in Å. If ``[step]`` is not given, a default value 0.1 is used. * ``-e`` Generate the input file for BVEL mode. .. note:: Since the calculation conditions are case dependent, fully automatic generation of the input file is not a realistic way. Some parameters can be set to unreasonable values in the automatic generations. All the users have to check and edit the generated input files carefully before running the map calculation. .. warning:: PyAbstantia does not handle the formal charges in CIF. Users must specify the formal charges explicitly in the input file. Tutorial ======== Na\ :sub:`3`\ V\ :sub:`2`\ (PO\ :sub:`4`\ )\ :sub:`2`\F\ :sub:`3`\ ------------------------------------------------------------------ BVS ^^^ In this tutorial, we will use a CIF as an input. So you need to install pymatgen_ to use the CIF parser. Download a CIF file from `Crystallographic Open Database (COD) `_. :: $ curl -O http://www.crystallography.net/cod/1521543.cif or :: $ wget http://www.crystallography.net/cod/1521543.cif The source of CIF is: Le Meins, J.M.; Crosnier-Lopez, M.P.; Hemon-Ribaud, A.; Courbion, G., *Journal of Solid State Chemistry*, **148(2)**, 260--270 (1999) `DOI: 10.1006/jssc.1999.8447 `_ Just run PyAbstantia in the command line prompt: :: $ pyabst -mp 8 -a -r -e 1521543.cif Answer to several prompts: :: Input file: 1521543.cif --- CIF mode --- Input target ion Na Input a formal valence number of target ion. 1.0 Input a number of species for counter ion. 2 Input counter ion species 1 of 2 O Input counter ion species 2 of 2 F Resolution was set as 90 90 108 ----------------------------------------- 1521543.inp is generated. 1521543_BVEL.inp is generated. ----------------------------------------- Title: 1521543 Lattice Parameters: a = 9.047 Å, b = 9.047 Å, c = 10.705 Å alpha = 90.0°, beta = 90.0°, gamma = 90.0° Data points along each axes: 90 90 108 Number of Processes: 8 Multiprocessing is not applicable. No. of processes was reduced to 7. Multiprocessing is not applicable. No. of processes was reduced to 6. Output file: 1521543.pgrid ---------------------------------------- Calculation time for 3D-BVS: 7.18 sec done Then you will get following three files. * ``1521543.inp``: input file for BVS * ``1521543.pgrid``: 3D map data of BVS * ``1521543_BVEL.inp``: input file for BVEL Open the ``5121543.inp`` with your text editor and check the parameters. If you edit the input file, you need to rerun PyAbstantia. :: $ pyabst -mp 6 1521543.inp After running PyAbstantia, open the CIF by VESTA_ and import ``1521543.pgrid``. Set the isosurface value to 0.2, and disable the sections. .. image:: ./images/NVPF3223_BVS.jpg :scale: 60% You can visualize multiple isosurface levels simultaneously. (:math:`|\Delta V|` = 0.1 and 0.5) .. image:: ./images/NVPF3223_BVS_m.jpg :scale: 60% BVEL ^^^^ Open and edit ``1521543_BVEL.inp``. (You must change the formal valence of V, and input the Morse potential parameters for the Na---F bond.) Run PyAbstantia. :: $ pyabst -mp 8 1521543_BVEL.inp Then you will get ``1521543_BVEL.pgrid`` storing the BVEL map. The isosurfaces in the below image were drawn at levels at -2.9 and 1.4 eV (0.5 and 2.0 eV above the lowest energy, respectively). .. image:: ./images/NVPF3223_BVEL.jpg :scale: 60% .. raw:: html .. _Python: https://www.python.org .. _pymatgen: http://pymatgen.org .. _3DBVSMAPPER: https://doi.org/10.1107/S0021889812032906 .. _softness sensitive BVS: http://doi.org/10.1107/S0108768101003068 .. _Bond_Str: https://www.ill.eu/sites/fullprof/php/programsdceb.html?pagina=Bond_Str .. _`BVS Mapping`: http://pcwww.liv.ac.uk/~msd30/software/BVS_Mapping.html .. _NumPy: http://www.numpy.org .. _RIETAN-FP: http://fujioizumi.verse.jp/download/download_Eng.html .. _VESTA: http://jp-minerals.org/vesta/en/ .. _COD: http://www.crystallography.net/cod/