Merge pull request #1 from OctaDist/nightly-build

from Nightly build v.2.5.2.2

Author: rangsimanketkaew

.travis.yml

@@ -10,12 +10,13 @@ python:
   - "3.7"  # 3.7 development branch
 
 install:
-  - pip install octadist
+  # - pip install octadist
+  - pip install -i https://test.pypi.org/simple/ octadist
 
 script:
   - cd example-py
   - python example_1.py
   - python example_2.py
   - python example_3.py
   - python example_4.py
-
+  - python example_5.py

README.md

@@ -1,39 +1,60 @@
 [![Travis-CI Test](https://img.shields.io/travis/OctaDist/OctaDist-PyPI/master.svg
 )](https://travis-ci.org/OctaDist/OctaDist-PyPI)
-[![Github release](https://img.shields.io/github/release/OctaDist/OctaDist-PyPI.svg
-)](https://github.com/OctaDist/OctaDist/releases)
-[![Code size](https://img.shields.io/github/languages/code-size/OctaDist/OctaDist-PyPI.svg)](https://github.com/OctaDist/OctaDist-PyPI)
-[![Repo size](https://img.shields.io/github/repo-size/OctaDist/OctaDist-PyPI.svg)](https://github.com/OctaDist/OctaDist-PyPI)
+![Python version](https://img.shields.io/pypi/pyversions/octadist.svg)
+![Python Wheel](https://img.shields.io/pypi/wheel/octadist.svg)
+![Code size](https://img.shields.io/github/languages/code-size/OctaDist/OctaDist-PyPI.svg)
+![Repo size](https://img.shields.io/github/repo-size/OctaDist/OctaDist-PyPI.svg)
 
-## OctaDist-PyPI
-Octahedral distortion calculator: A program for determining the structural distortion of the octahedral complexes. https://octadist.github.io/
+## OctaDist
+
+Octahedral distortion calculator: 
+A tool for calculating distortion parameters in coordination complexes. 
+https://octadist.github.io/
 
 <p align="center">
-   <img alt="molecule" src="https://raw.githubusercontent.com/OctaDist/OctaDist/master/images/molecule.png" align=middle width="200pt" />
+   <img alt="molecule" 
+   src="https://raw.githubusercontent.com/OctaDist/OctaDist-PyPI/master/images/molecule.png" 
+   align=middle 
+   width="200pt" />
 <p/>
 
 This program is written entirely in Python 3 and tested on PyCharm (Community Edition). 
 
-## Installation
-- Install the latest version: `pip install octadist`
-- Upgrade to the latest version: `pip install --upgrade octadist`
-- Upgrade/downgrade to a specific version: `pip install --upgrade octadist==2.5.0`
+## Features
 
-## Sample usage
-Example scripts are available at [here](https://github.com/OctaDist/OctaDist-PyPI/tree/master/example-py).
+OctaDist is designed as a smart tool used for studying the structural distortion in coordinate complexes.
+With the abilities of OctaDist, you can:
 
-First of all, you have to import necessary modules for computing the octahedral distortion parameters, called `calc`:
+- identify the type of octahedral coordination complexes.
+- compute octahedral distortion parameters.
+- display 3D molecule and other stuff.
+- implement its functionality in your or other program.
 
-```
-from octadist import calc
-```
 
-Prepare list (or array) for atomic labels and coordinates:
+## Getting started
+
+All details of OctaDist is available at [user manual](https://octadist.github.io/manual.html) on the website.
+
+
+## Installing
+
+- Install the latest version: 
+  ```
+  pip install octadist
+  ```
+- Upgrade/downgrade to a specific version: 
+  ```
+  pip install --upgrade octadist==2.5.1
+  ```
+  
+## Running the test
+
+Prepare two lists of atomic symbols and atomic coordinates, the latter can be stored in array:
 
 ```
 atom = ['Fe', 'O', 'O', 'N', 'N', 'N', 'N']
 
-coor = [[2.298354000, 5.161785000, 7.971898000],
+coor = [[2.298354000, 5.161785000, 7.971898000],  # <- Metal center atom
         [1.885657000, 4.804777000, 6.183726000],
         [1.747515000, 6.960963000, 7.932784000],
         [4.094380000, 5.807257000, 7.588689000],
@@ -42,50 +63,60 @@ coor = [[2.298354000, 5.161785000, 7.971898000],
         [2.886404000, 5.392925000, 9.848966000]]
 ```
 
-or you can open input file and extract the octahedral structure from input metal complex using a module called `coord`:
+Import necessary module for computing the octahedral distortion parameters, called `calc`:
 
 ```
-from octadist import coord, calc
+from octadist import calc
 ```
 
-For example, input file `full\path\of\your\input\file\Multiple-metals.xyz` 
-(other example input files are available at [here](https://github.com/OctaDist/OctaDist-PyPI/tree/master/example-input)):
+Then calculate all parameters separately, for example:
 
 ```
-file = r"full\path\of\your\input\file\Multiple-metals.xyz"
-
-atom, coor = coord.extract_octa(file)
+d_bond = octadist.calc_d_bond(coor)         # Bond distance
+d_mean = octadist.calc_d_mean(coor)         # Mean distance
+zeta = octadist.calc_zeta(coor)             # Zeta
+delta = octadist.calc_delta(coor)           # Delta
+angle = octadist.calc_bond_angle(coor)      # Bond angle
+sigma = octadist.calc_sigma(coor)           # Sigma
+theta = octadist.calc_theta(atom, coor)     # Theta
 ```
 
-Then calculate all octahedral parameters
+or calculate them at once:
 
 ```
-d_mean, zeta, delta, sigma, theta = calc.calc_all(atom, coor)
+zeta, delta, sigma, theta = calc.calc_all(coor)
 ```
 
-and print all computed parameters:
+Then print all computed parameters:
 
 ```
-All computed parameters
------------------------
-Zeta  = 0.22807256171728651
-Delta = 0.0004762517834704151
-Sigma = 47.926528379270124
-Theta = 122.688972774546
+Computed parameters
+-------------------
+Zeta  = 0.228072561
+Delta = 0.000476251
+Sigma = 47.92652837
+Theta = 122.6889727
 ```
 
-Please cite this project when you use OctaDist for scientific publication.
+Example scripts and coordinate files are available at 
+[example-py](https://github.com/OctaDist/OctaDist-PyPI/tree/master/example-py) and at
+[example-input](https://github.com/OctaDist/OctaDist-PyPI/tree/master/example-input).
+
+## Citation
+
+Please cite this project when you have used OctaDist for scientific publication.
 
 ```
-OctaDist - A program for determining the structural distortion of the octahedral complexes.
+OctaDist: A tool for calculating distortion parameters in coordination complexes.
 https://octadist.github.io
 ```
 
-
 ## Bug report
+
 If you found issues in OctaDist, please report us at [here](https://github.com/OctaDist/OctaDist/issues).
 
 ## Project team
+
 - [Rangsiman Ketkaew](https://sites.google.com/site/rangsiman1993) (Thammasat University) <br/>
   - E-mail: rangsiman1993@gmail.com <br/>
 - [Yuthana Tantirungrotechai](https://sites.google.com/site/compchem403/people/faculty/yuthana) (Thammasat University)

example-py/example_1.py

@@ -1,29 +1,34 @@
+###################################################
+# Example 1 for running the test on OctaDist PyPI #
+###################################################
+
 from octadist import calc
 
-#############
-# Example 1 #
-#############
+# The first atom must be metal center atom of octahedral structure.
+# If not, please see example_2.py for how to handle this issue.
 
-# Prepare two lists for atomic labels and coordinates (or array for the latter)
 atom = ['Fe', 'O', 'O', 'N', 'N', 'N', 'N']
 
-coor = [[2.298354000, 5.161785000, 7.971898000],
+coor = [[2.298354000, 5.161785000, 7.971898000],  # <- Metal atom
         [1.885657000, 4.804777000, 6.183726000],
         [1.747515000, 6.960963000, 7.932784000],
         [4.094380000, 5.807257000, 7.588689000],
         [0.539005000, 4.482809000, 8.460004000],
         [2.812425000, 3.266553000, 8.131637000],
         [2.886404000, 5.392925000, 9.848966000]]
 
-# Calculate all octahedral parameters
-d_mean, zeta, delta, sigma, theta = calc.calc_all(atom, coor)
+zeta, delta, sigma, theta = calc.calc_all(coor)
 
-# Show all computed parameters
-print("\nEx.1: All computed parameters")
-print("-----------------------------")
-print("Mean distance =", d_mean)
-print("         Zeta =", zeta)
-print("        Delta =", delta)
-print("        Sigma =", sigma)
-print("        Theta =", theta)
+print("\nAll computed parameters")
+print("-----------------------")
+print("Zeta  =", zeta)
+print("Delta =", delta)
+print("Sigma =", sigma)
+print("Theta =", theta)
 
+# All computed parameters
+# -----------------------
+# Zeta  = 0.22807256171728651
+# Delta = 0.0004762517834704151
+# Sigma = 47.926528379270124
+# Theta = 122.688972774546

example-py/example_2.py

@@ -1,24 +1,36 @@
-from octadist import coord, calc
+###################################################
+# Example 2 for running the test on OctaDist PyPI #
+###################################################
 
-#############
-# Example 2 #
-#############
+from octadist import calc, coord
 
-# Open and read input file
-file = r"../example-input/Multiple-metals.xyz"
+atom = ['O', 'O', 'Fe', 'N', 'N', 'N', 'N']
 
-# Extract atomic labels and coordinates of octahedral structure from metal complex
-atom, coor = coord.extract_octa(file)
+coor = [[1.885657000, 4.804777000, 6.183726000],
+        [1.747515000, 6.960963000, 7.932784000],
+        [2.298354000, 5.161785000, 7.971898000],  # <- Metal atom
+        [4.094380000, 5.807257000, 7.588689000],
+        [0.539005000, 4.482809000, 8.460004000],
+        [2.812425000, 3.266553000, 8.131637000],
+        [2.886404000, 5.392925000, 9.848966000]]
 
-# Calculate all octahedral parameters
-d_mean, zeta, delta, sigma, theta = calc.calc_all(atom, coor)
+# What if the first atom in atomic symbol and coordinates lists are not metal atom,
+# you can also use coord.extract_octa to rearrange the sequence of atom in list.
 
-# Show all computed parameters
-print("\nEx.2: All computed parameters")
-print("-----------------------------")
-print("Mean distance =", d_mean)
-print("         Zeta =", zeta)
-print("        Delta =", delta)
-print("        Sigma =", sigma)
-print("        Theta =", theta)
+atom_octa, coor_octa = coord.extract_octa(atom, coor)
 
+zeta, delta, sigma, theta = calc.calc_all(coor_octa)
+
+print("\nAll computed parameters")
+print("-----------------------")
+print("Zeta  =", zeta)
+print("Delta =", delta)
+print("Sigma =", sigma)
+print("Theta =", theta)
+
+# All computed parameters
+# -----------------------
+# Zeta  = 0.22807256171728651
+# Delta = 0.0004762517834704151
+# Sigma = 47.926528379270124
+# Theta = 122.688972774546

example-py/example_3.py

@@ -1,26 +1,31 @@
+###################################################
+# Example 3 for running the test on OctaDist PyPI #
+###################################################
+
 from octadist import coord, calc
 
-#############
-# Example 3 #
-#############
+# You can also import your input file, like this:
 
-# Open and read input file
 file = r"../example-input/Multiple-metals.xyz"
 
-# If complex contains metal center more than one, you can specify the index of metal of interest.
-# For example, this complex contains three metal atoms: Fe, Ru, and Rd. I add second argument "2"
-# for computing the parameter for Ru metal center atom.
-atom, coor = coord.extract_octa(file, 2)
+# Then use coord.extract_file to extract all atomic symbols and coordinates,
+# and then use coord.extract_octa for taking the octahedral structure.
+
+atom_full, coor_full = coord.extract_file(file)
+atom_octa, coor_octa = coord.extract_octa(atom_full, coor_full)
 
-# Calculate all octahedral parameters
-d_mean, zeta, delta, sigma, theta = calc.calc_all(atom, coor)
+zeta, delta, sigma, theta = calc.calc_all(coor_octa)
 
-# Show all computed parameters
-print("\nEx.3: All computed parameters")
-print("-----------------------------")
-print("Mean distance =", d_mean)
-print("         Zeta =", zeta)
-print("        Delta =", delta)
-print("        Sigma =", sigma)
-print("        Theta =", theta)
+print("\nAll computed parameters")
+print("-----------------------")
+print("Zeta  =", zeta)
+print("Delta =", delta)
+print("Sigma =", sigma)
+print("Theta =", theta)
 
+# All computed parameters
+# -----------------------
+# Zeta  = 0.0030146365519487794
+# Delta = 1.3695007180404868e-07
+# Sigma = 147.3168033970211
+# Theta = 520.6407679851042

example-py/example_4.py

@@ -1,13 +1,32 @@
-from octadist import coord, draw
+###################################################
+# Example 4 for running the test on OctaDist PyPI #
+###################################################
 
-#############
-# Example 4 #
-#############
+from octadist import coord, calc
 
-# Open and read input file
 file = r"../example-input/Multiple-metals.xyz"
 
-# Graphical display for octahedral complex
-full_atom, full_coor = coord.get_coord(file)
-draw.all_atom(full_atom, full_coor)
+atom_full, coor_full = coord.extract_file(file)
 
+# If complex contains metal center more than one, you can specify the index metal
+# whose octahedral structure will be computed.
+# For example, this complex contains three metal atoms: Fe, Ru, and Rd.
+# I add "2" as a second argument for choosing Ru as metal of interest.
+
+atom_octa, coor_octa = coord.extract_octa(atom_full, coor_full, 2)
+
+zeta, delta, sigma, theta = calc.calc_all(coor_octa)
+
+print("\nAll computed parameters")
+print("-----------------------")
+print("Zeta  =", zeta)
+print("Delta =", delta)
+print("Sigma =", sigma)
+print("Theta =", theta)
+
+# All computed parameters
+# -----------------------
+# Zeta  = 0.001616439510534251
+# Delta = 3.5425830613072754e-08
+# Sigma = 1.26579367508117
+# Theta = 4.177042495798965

example-py/example_5.py

@@ -0,0 +1,18 @@
+###################################################
+# Example 5 for running the test on OctaDist PyPI #
+###################################################
+
+from octadist import coord, draw
+
+file = r"../example-input/Multiple-metals.xyz"
+
+# Graphical display for octahedral complex
+
+atom_full, coor_full = coord.extract_file(file)
+draw.all_atom(atom_full, coor_full)
+
+# Display and automatically save image as .png file with user-specified name
+
+draw.all_atom(atom_full, coor_full, "complex_octadist")
+
+# Output image, complex_octadist.png, is stored at ../images directory