Merge pull request #7 from MikeHeiber/development

Development Branch Ready for Next Beta Release Candidate

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "KMC_Lattice"]
 	path = KMC_Lattice
 	url = https://github.com/MikeHeiber/KMC_Lattice
+[submodule "googletest"]
+	path = googletest
+	url = https://github.com/google/googletest

.travis.yml

@@ -0,0 +1,47 @@
+# Copyright (c) 2018 Michael C. Heiber
+# This source file is part of the Excimontec project, which is subject to the MIT License.
+# For more information, see the LICENSE file that accompanies this software.
+# The Excimontec project can be found on Github at https://github.com/MikeHeiber/Excimontec
+# Travis CI continuous integration build script
+
+language: cpp
+os: linux
+dist: trusty
+sudo: required
+
+compiler:
+    - gcc
+
+env:
+    - OPTIONS="GCC_VERSION=5 && MPI=openmpi && TARGET=test_coverage"
+    - OPTIONS="GCC_VERSION=4.7 && MPI=mpich2 && TARGET=test"
+    - OPTIONS="GCC_VERSION=4.7 && MPI=openmpi && TARGET=test"
+    - OPTIONS="GCC_VERSION=4.8 && MPI=mpich2 && TARGET=test"
+    - OPTIONS="GCC_VERSION=4.8 && MPI=openmpi && TARGET=test"
+    - OPTIONS="GCC_VERSION=4.9 && MPI=mpich2 && TARGET=test"
+    - OPTIONS="GCC_VERSION=4.9 && MPI=openmpi && TARGET=test"
+    - OPTIONS="GCC_VERSION=5 && MPI=mpich2 && TARGET=test"
+    - OPTIONS="GCC_VERSION=5 && MPI=openmpi && TARGET=test"
+    - OPTIONS="GCC_VERSION=6 && MPI=mpich2 && TARGET=test"
+    - OPTIONS="GCC_VERSION=6 && MPI=openmpi && TARGET=test"
+    - OPTIONS="GCC_VERSION=7 && MPI=mpich2 && TARGET=test"
+    - OPTIONS="GCC_VERSION=7 && MPI=openmpi && TARGET=test"
+    - OPTIONS="GCC_VERSION=8 && MPI=mpich2 && TARGET=test"
+    - OPTIONS="GCC_VERSION=8 && MPI=openmpi && TARGET=test"
+
+before_install:
+    - eval "${OPTIONS}"
+    - sudo add-apt-repository ppa:ubuntu-toolchain-r/test -y
+    - sudo apt-get update -qq
+    - sudo apt-get install -qq gcc-$GCC_VERSION g++-$GCC_VERSION -y
+    - sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-$GCC_VERSION 60 --slave /usr/bin/g++ g++ /usr/bin/g++-$GCC_VERSION
+    - sudo update-alternatives --config gcc
+    - gcc --version
+    - if [[ "$MPI" = mpich2 ]]; then sudo apt-get -y install -qq mpich2 libmpich2-dev; fi
+    - if [[ "$MPI" = openmpi ]]; then sudo apt-get -y install -qq openmpi-bin libopenmpi-dev; fi
+    - if [[ "$TARGET" = test_coverage ]]; then pip install --user cpp-coveralls; fi
+
+script:
+    - make -j10 $TARGET && travis_wait ./test/Excimontec_tests.exe
+    - if [[ "$TARGET" = test_coverage ]]; then coveralls --include src --exclude "googletest/*" --gcov-options '\-lp'; fi
+    - if [[ "$TARGET" = test ]]; then make -j10 && mpiexec -n 4 ./Excimontec.exe parameters_default.txt; fi

Doxyfile

@@ -38,13 +38,13 @@ PROJECT_NAME           = Excimontec
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = v1.0-beta.3
+PROJECT_NUMBER         = v1.0-beta.4
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          = "An open-source KMC simulation software package for modeling organic semiconductor materials and devices, such as OPVs, OLEDs, and more"
+PROJECT_BRIEF          = "An open-source KMC simulation software package for modeling the optoelectronic processes in organic semiconductor materials and devices, such as OPVs, OLEDs, and more."
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55
@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = Z:\Software_Projects\Local\Excimontec\docs
+OUTPUT_DIRECTORY       = docs
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -790,7 +790,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = Z:\Software_Projects\Local\Excimontec
+INPUT                  = .
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -873,7 +873,9 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = 
+EXCLUDE                = googletest \
+                         KMC_Lattice \
+                         test
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded

README.md

@@ -1,12 +1,17 @@
 # Excimontec
-The goal of this project is to develop an open-source KMC simulation software package for modeling organic semiconductor materials and devices, such as OPVs, OLEDs, and more. 
-The software is being developed in modern C++ and is optimized for efficient execution on high performance computing clusters using MPI. 
-This software package uses object-oriented design and extends the [KMC_Lattice](https://github.com/MikeHeiber/KMC_Lattice) framework.
+
+Kinetic Monte Carlo simulations are a powerful computational tool that have been used in concert with experiments and more detailed theoretical methods to understand and optimize organic semiconductor materials and devices. 
+However, despite over 30 years of applying KMC tools to organic semiconductors, no widespread or standardized software tools have taken hold in the community. 
+Instead, many research groups around the world have maintained private codebases of varying complexity, efficiency, and reliability. 
+As a result, there have been large barriers to entry for new researchers and a lot of repeated effort throughout the community that would be much better off applied to pushing the capabilities of the technique and further refining the physical models. 
+
+Excimontec represents an honest effort to bring the community together around a well-tested, optimized, reliable, and accessible open-source tool for performing KMC simulations of organic electronic devices. The software is being developed in modern C++ and is optimized for efficient execution on high performance computing clusters using MPI. 
+This software package uses object-oriented design and extends the [KMC_Lattice](https://github.com/MikeHeiber/KMC_Lattice) framework. 
 
 #### Major Features:
 - Adjustable periodic boundary conditions in all three directions allow users to perform 1D, 2D, or 3D simulations.
 - Choose between several film architectures, including a neat film, bilayer film, or random blend film.
-- Import bulk heterojunction morphologies generated by [Ising_OPV v3.2 and v4](https://github.com/MikeHeiber/Ising_OPV).
+- Import bulk heterojunction morphologies generated by [Ising_OPV](https://github.com/MikeHeiber/Ising_OPV) v3.2 and v4.
 - Donor and acceptor materials can take on an uncorrelated Gaussian DOS, a correlated Gaussian DOS with different correlation functions, or an uncorrelated exponential DOS model.
 - Dynamics test simulations can be performed to generate exciton and charge carrier density transients that can be used to model exciton dissociation, charge carrier separation, and charge carrier recombination kinetics.
 - Time-of-flight charge transport simulations of electrons or holes can be performed on neat, random blend, or bulk heterojunction blend films.
@@ -18,45 +23,65 @@ This software package uses object-oriented design and extends the [KMC_Lattice](
 - Choose between several KMC algorithms (first reaction method, selective recalculation method, or full recalculation method).
 
 ## Current Status
-The current release (Excimontec v1.0-beta.3) is built with KMC_Lattice v2.0-beta.3 and allows the user to perform several simulation tests relevant for OPV and OLED devices. 
+
+The current release, Excimontec
+[![GitHub (pre-)release](https://img.shields.io/github/release/MikeHeiber/Excimontec/all.svg?style=flat-square)](https://github.com/MikeHeiber/Excimontec/releases)
+, is built with KMC_Lattice [![GitHub (pre-)release](https://img.shields.io/github/release/MikeHeiber/KMC_Lattice/all.svg?style=flat-square)](https://github.com/MikeHeiber/KMC_Lattice/releases) and allows the user to perform several simulation tests relevant for OPV and OLED devices. 
 All major planned features that are to be included in v1.0 are now implemented and have undergone preliminary testing. 
 However, this software tool is still under development, and as such, there may still be bugs that need to be squashed. 
 Please report any bugs or submit feature requests in the [Issues](https://github.com/MikeHeiber/Excimontec/issues) section. 
 
 Major releases and other significant developments will be announced on the Excimontec: General News mailing list. If you are interested in keeping up to date with the development and application of this tool, please subscribe at the following link:
 [Subscribe Here](http://eepurl.com/dis9AT)
 
-Travis CI continuous integration status:
+#### Continuous Integration and Testing Status:
 
-Excimontec is currently being tested on Ubuntu v14.04 with the GCC compiler (versions 4.7, 4.8, 4.9, 5, 6, and 7) and on both OpenMPI v1.6.5 and MPICH v3.04.
+Excimontec is currently being tested on [Ubuntu](https://www.ubuntu.com/) v14.04 with the [GCC compiler](https://gcc.gnu.org/) (versions 4.7, 4.8, 4.9, 5, 6, 7, and 8) and on both [Open MPI](http://www.open-mpi.org/) v1.6.5 and [MPICH](http://www.mpich.org/) v3.04 using [Travis CI](https://travis-ci.com/).
 
-Master branch: [![Build Status](https://travis-ci.org/MikeHeiber/Excimontec.svg?branch=master)](https://travis-ci.org/MikeHeiber/Excimontec)
+| Branch | Status |
+| :------: | ------ |
+| Master | [![Build Status](https://img.shields.io/travis/MikeHeiber/Excimontec/master.svg?style=for-the-badge)](https://travis-ci.org/MikeHeiber/Excimontec) |
+| Development | [![Build Status](https://img.shields.io/travis/MikeHeiber/Excimontec/development.svg?style=for-the-badge)](https://travis-ci.org/MikeHeiber/Excimontec) |
 
-Development branch: [![Build Status](https://travis-ci.org/MikeHeiber/Excimontec.svg?branch=development)](https://travis-ci.org/MikeHeiber/Excimontec)
+Code is being tested using [googletest](https://github.com/google/googletest) with test coverage assessment by [Coveralls](https://coveralls.io/).
 
-## Work Together
+| Branch | Status |
+| :------: | ------ |
+| Master | [![Coveralls github branch](https://img.shields.io/coveralls/github/MikeHeiber/Excimontec/master.svg?style=for-the-badge)](https://coveralls.io/github/MikeHeiber/Excimontec?branch=master) |
+| Development | [![Coveralls github branch](https://img.shields.io/coveralls/github/MikeHeiber/Excimontec/development.svg?style=for-the-badge)](https://coveralls.io/github/MikeHeiber/Excimontec?branch=development) |
+
+## Contact
 
 If you would like to contribute to the development of this project or would like some help in using the tool for your research, please contact me ([email protected]) to discuss a collaboration. 
 You can check out my KMC research and other work on [Researchgate](https://www.researchgate.net/profile/Michael_Heiber).
 
-Have a quick question or want to chat about Excimontec?  Join the dicussion on Gitter: [![Gitter chat](https://badges.gitter.im/Excimontec.png)](https://gitter.im/Excimontec)
+Have a quick question or want to chat about Excimontec?  Join the discussion on Gitter: [![Gitter](https://img.shields.io/gitter/room/nwjs/nw.js.svg?style=for-the-badge)
+](https://gitter.im/Excimontec)
 
 ## How to try Excimontec?
 
-#### Building an Executable
+#### Building and Testing the Executable
 
 This software tool uses [Message Passing Interface (MPI)](https://computing.llnl.gov/tutorials/mpi/) to utilize parallel computing power. 
 As a result, using Excimontec requires that an MPI library is pre-installed on your system, and the final Excitmontec executable must be built on your specific system. 
 We cannot provide pre-built binaries for your system. 
 Contact your HPC admin to determine the protocols for building MPI applications on your HPC system. 
-In many cases, the HPC system will already be configured for you, and the package comes with a default makefile that can be used with the [GCC compiler](https://gcc.gnu.org/). 
+In many cases, the HPC system will already be configured for you, and the package comes with a default makefile that can be used with the [GCC compiler](https://gcc.gnu.org/) or the [PGI compiler](https://www.pgroup.com/). 
 
 If you wish, you can also install MPI on your own personal workstation and then build Excimontec there as well. For development and preliminary simulation tests, sometimes it is more efficient to run on your own workstation instead of an HPC system. More information about common MPI packages can be found here:
-- http://www.open-mpi.org/
-- http://www.mpich.org/
-- http://mvapich.cse.ohio-state.edu/
+- Open MPI, http://www.open-mpi.org/
+- MPICH, http://www.mpich.org/
+- MVAPICH, http://mvapich.cse.ohio-state.edu/
+
+Once you have an MPI library installed, to build Excimontec, copy the Excimontec directory to your machine, set it as your working directory, and run `make`. 
+Compilation flags have been set for GCC and PGI compilers.  If you are using another compiler, you will need to edit the makefile and define your own compiler options.
+Once the normal build is successful, you should test Excimontec on your own hardware using the unit and system tests provided before you use the tool. 
+Build the testing executable by running `make test`. 
+Once the test build is complete, navigate to the testing directory, and run `./Excimontec_tests.exe`.
+Please report any build or testing errors in the [Issues](https://github.com/MikeHeiber/Excimontec/issues) section. 
 
 #### Usage
+
 In most cases, your HPC system will use a job scheduler to manage the computing workload. 
 For performing Excimontec simulations, it is recommended to submit batch jobs where you will request the resources needed to perform the simulation. 
 An example batch script for the [SLURM](https://slurm.schedmd.com/) job scheduling system is provided with this package (slurm_script.sh). 
@@ -67,11 +92,13 @@ Excimontec.exe takes one required input argument, which is the filename of the i
 An example parameter file is provided with this package (parameters_default.txt).
 
 For example, within the batch script, to create a simulation that runs on 10 processors, an the execution command is:
->    mpiexec -n 10 Excimontec.exe parameters_default.txt
+
+```mpiexec -n 10 Excimontec.exe parameters_default.txt```
 
 In this example, the parameters_default.txt file that is located in the current working directory is loaded into the Excimontec program to determine what simulation to run.
 
 #### Output
+
 Excimontec will create a number of different output files depending which test is chosen in the parameter file:
 - results#.txt -- This text file will contain the results for each processor where the # will be replaced by the processor ID.
 - analysis_summary.txt -- When MPI is enabled, this text file will contain average final results from all of the processors.
@@ -80,10 +107,13 @@ Excimontec will create a number of different output files depending which test i
 - ToF_transit_time_dist.txt -- When performing a time-of-flight charge transport test, the resulting polaron transit time probability distribution will be output to this file.
 - ToF_results.txt -- When performing a time-of-flight charge transport test, the resulting quantitative results are put into this parsable delimited results file.
 - Charge_extraction_map#.txt -- When performing a time-of-flight or IQE test, the x-y locations where charges are extracted from the lattice are saving into this map file.
+- DOS_correlation_data#.txt -- When a correlated density of states model is enabled, data showing the statistical correlation of site energies vs. distance is output into this file.
 
 #### Data Analysis
+
 For [Igor Pro](https://www.wavemetrics.com/) users, I am developing an open-source procedures package for loading, analyzing, and plotting data from Excimontec simulations called [Excimontec_Analysis](https://github.com/MikeHeiber/Excimontec_Analysis). 
 This is a good starting point for managing the data generated by Excimontec, and the Igor Pro scripting environment provides a nice playground where users can perform more advanced data analysis as needed.
 
 ## For Software Developers
+
 Public API documentation for the Excimontec package is still under development and can be viewed [here](https://mikeheiber.github.io/Excimontec/).