Merge pull request #78 from freude/develop

Develop

.travis.yml

@@ -3,7 +3,7 @@ python:
     - "3.6"
 # command to install dependencies
 install:
-    - sudo apt-get install mpich
+    - sudo apt-get install libopenmpi-dev
     - pip install python-coveralls
     - pip install coverage
     - pip install -r requirements.txt

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = Nanonet
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md → docs/source/README.md

@@ -1,8 +1,12 @@
 # NanoNet
 
-[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Codacy Badge](https://api.codacy.com/project/badge/Grade/5186e15b951d4df6b4f20c2365870b7c)](https://app.codacy.com/app/freude/NanoNet?utm_source=github.com&utm_medium=referral&utm_content=freude/NanoNet&utm_campaign=Badge_Grade_Dashboard)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Build Status](https://travis-ci.org/freude/NanoNet.svg)](https://travis-ci.org/freude)
 [![Coverage Status](https://coveralls.io/repos/github/freude/NanoNet/badge.svg?branch=develop)](https://coveralls.io/github/freude/NanoNet?branch=develop)
+[![CodeFactor](https://www.codefactor.io/repository/github/freude/nanonet/badge/master)](https://www.codefactor.io/repository/github/freude/nanonet/overview/master)
+
+<img src="https://user-images.githubusercontent.com/4588093/65398380-1f684380-ddfa-11e9-9e87-5aab6cf417b8.png" width="200">
 
 ## Introduction
 
@@ -24,7 +28,7 @@ git clone https://github.com/freude/NanoNet.git
 cd NanoNet
 ```
 
-All dependencies may be installed at once by invoking the following command
+All dependencies can be installed at once by invoking the following command
  from within the source directory:
 
 ```bash
@@ -48,6 +52,14 @@ All tests may be run by invoking the command:
 nosetests --with-doctest
 ```
 
+### Examples of usage
+
+- [Atomic chain](jupyter_notebooks/atom_chains.ipynb)
+- [Huckel model](jupyter_notebooks/Hukel_model.ipynb)
+- [Bulk silicon](jupyter_notebooks/bulk_silicon.ipynb)
+- [Bulk silicon - initialization via an input file](jupyter_notebooks/bulk_silicon_with_input_file.ipynb)
+- [Silicon nanowire](jupyter_notebooks/silicon_nanowire.ipynb)
+
 ### Python interface
 
 Below is a short example demonstrating usage of the `tb` package.
@@ -66,10 +78,10 @@ Below we demonstrate band structure computation for bulk silicon using empirical
  is shown in examples in the ipython notebooks. Here we use predefined basis sets.
 
     ```python
-    tb.Atom.orbital_sets = {'Si': 'SiliconSP3D5S'}
+    tb.Orbitals.orbital_sets = {'Si': 'SiliconSP3D5S'}
     ```
 
-2. Specify geometry of the system - determine position if atoms
+2. Specify geometry of the system - determine position of atoms
 and specify periodic boundary conditions if any. This is done by creating an object of 
 the class Hamiltonian with proper arguments.
 
@@ -126,65 +138,60 @@ the class Hamiltonian with proper arguments.
 
 The package is equipped with the command line tool `tb` the usage of which reads:
 
-```tb [-h] [--k_points_file K_POINTS_FILE] param_file```
-
-    Mandatory argument:
+```
+tb [-h] [--k_points_file K_POINTS_FILE] [--xyz XYZ] 
+   [--show SHOW] [--save SAVE] 
+   [--code_name CODE_NAME] param_file
     
-    param_file
-        is an file in the yaml-format containing all parameters
-        needed to run computations.
+    positional arguments:
+      param_file            Path to the file in the yaml-format containing all
+                            parameters needed to run computations.
     
-    Optional arguments and parameters:
+    optional arguments:
+      -h, --help            show this help message and exit
+      --k_points_file K_POINTS_FILE
+                            Path to the txt file containing coordinates of wave
+                            vectors for the band structure computations. If not
+                            specified, default values will be used.
+      --xyz XYZ             Path to the file containing atomic coordinates. If
+                            specified, it overrides the coordinates specified in
+                            the param_files.
+      --show SHOW, -S SHOW  Show figures, 0/1/2. 0 shows nothing, 1 outputs
+                            figures on screen, 2 saves figures on disk without
+                            showing.
+      --save SAVE, -s SAVE  Save results of computations on disk, 0/1.
+      --code_name CODE_NAME
+                            Code name is added to the names of all saved data
+                            files.
+```
 
-    --k_points_file K_POINTS_FILE
-        path to the txt file containing coordinates of
-        wave vectors for the band structure computations. 
-        If not specified, default values will be used. 
-    -h
-        with this parameter the information about 
-        command usage will be output.
 
 The results of computations will be stored in `band_structure.pkl` file in the current directory.
+This file name can be modified by specifying the parameter `--code_name`.
 
-## Examples of usage
-
-- [Atomic chain](jupyter_notebooks/atom_chains.ipynb)
-- [Huckel model](jupyter_notebooks/Hukel_model.ipynb)
-- [Bulk silicon](jupyter_notebooks/bulk_silicon.ipynb)
-- [Bulk silicon - initialization via an input file](jupyter_notebooks/bulk_silicon_with_input_file.ipynb)
-- [Silicon nanowire](jupyter_notebooks/silicon_nanowire.ipynb)
-
-## Computational methods
-
-The code implements a family of tight-binding method for solids 
-(empirical tight-binding method) [] and molecules (Huckel method) []. 
-All computations are performed from known coupling coefficients and 
-energy spectrum of species. The Hamiltonian matrices are build from 
-a xyz-file containing atomic coordinates. The atomic coordinates are stored
- in the kd-tree which facilitates fast neighbour searching. 
- The criteria of being neighbours is specified by the nearst neighbour distance.
-  The angular dependence of the hoping matrix elements for two orbitals with
-   different orbital and magnetic quantum numbers is computed using 
-   semi-analytical approach proposed by [Podolskiy]. 
-
-## Customize your tight-binding code
-
-### Customize atomic properties
+On the computers with `mpi` functions installed, instead of `tb` one has to use its mpi-version `tbmpi`. 
+The script `tbmpi` parallelises the loop running over the wave vectors.
+This script can be used together with the command `mpirun` (below is an example generating 8 parallel processes):
 
-### Add distance dependence for hopping parameters
-
-## Deployment
-
-## Contributing
-
-## Versioning 
+```
+mpirun -n 8 tbmpi --show=2 --save=1 --xyz=si.xyz --k_points=k_points.txt input.yaml 
+```    
 
 ## Authors
 
+- Mykhailo V. Klymenko (mike.klymenko@rmit.edu.au)
+- Jackson S. Smith
+- Jesse A. Vaitkus
+- Jared H. Cole
+
 ## License
 
-## Acknowledgments
+This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details
 
+## Acknowledgments
 
+We acknowledge support of the RMIT University, 
+Australian Research Council through grant CE170100026, and
+National Computational Infrastructure, which is supported by the Australian Government.