Ready for v2.0.0-rc.1 (#53)

* Final enhancements for rc.1 (#52)

* Enhancements Update
- Resolves #35
- Resolves #48
- Resolves #49
- Resolves #50
- Resolves #51

General:
-Added more detailed building and testing instruction to README
-Added CONTRIBUTING.md file with details about how people can contribute to the project
-Added CHANGELOG.md file with a detailed list of changes in this release
-Updated README by adding links to the Changelog and the Contributing instructions file
-Changed Parameters_Simulation and Parameters_Lattice structs into classes
-Update copyright dates in Doxygen documentation for the Event, Lattice, Object, Simulation, Site, Parameters_Simulation, and Parameters_Lattice classes
-Added info about the new parameters classes to README
-Updated makefile to build the new parameters classes and added output of compiler warnings to the PGI compiler flags
-Updated Doxyfile with the next version number
-Fixed bug where Doxygen was not including the main markdown files in the documentation
-Updated Doxygen documentation

Lattice class:
-Updated init function to check the input lattice parameters and throw an invalid argument exception if they are not valid

Object class:
-Updated calculateDisplacement function to allow user to specify a direction for when one wants to calculate the absolute displacement only along a particular Cartesian direction

Parameters_Lattice class:
-Added checkParameters function to check the validity of the parameter member variables

Parameters_Simulation class:
-Added checkParameters function to check the validity of the parameter member variables
-Added nullptr as the default value for the Logfile pointer

Simulation class:
-Updated init function to check the input parameters and throw an invalid argument exception if they are not valid
-Updated init function lattice construction to use the Parameters_Lattice object within the Parameters_Simulation object

Utils:
-Added float variants of the createExponentialDOSVector and createGaussianDOSVector functions
-Added float versions of the calculateProbabilityHist functions to allow calculation of probability hists given a vector of float data
-Refactored createExponentialDOSVector and createGaussianDOSVector functionc to make them simpler and use the generate function to fill the ouput data vector
-Updated calculateProbabilityHist functions to filter input data vectors of any non finite numbers
-Fixed rare bug in calculateProbabilityHist function where the index was being calculated wrong due to floating point rounding error
-Updated vector_which_median function to cast the return of the distance function to int to prevent compiler warning
-Refactored all MPI functions to replace usage of for loops where possible by simpler copy, assign, and accumulate functions

tests:
-Updated ObjectTests to check the behavior of the updated Object calculateDisplacement function
-Updated SimulationTest AlgorithmTests by increasing N_tests to get better statistics and reduce likelihood of test failure
-Updated UtilsTests ExponentialDOSTests and GaussianDOSTests functions to also test the new float versions of DOS creation functions and calculateProbabilityHist functions
-Updated UtilsTests ExponentialDOSTests and GaussianDOSTests functions with comments to explain each test and more concise, accurate calculation of the prob dist peak height
-Updated Utils CalculateProbabilityHistTests by adding tests for the new float versions of the calculateProbabilityHist functions
-Refactored CalculateProbabilityHist Tests to use generate function for filling vectors with random numbers
-Added tests to CalculateProbabilityHistTests to check that the data filtering for non finite values is working properly
-Updated CalculateProbabilityHistTests by specifying the double version of the uniform_real_distribution, increasing the number of entries in the data vectors to increase statistically accuracy and reduce likelihood of test failure, and using the generate function to populate the data vectors
-Updated main by re-enabling command line output during the tests
-Updated all uses of count_if function by casting the return to int to prevent compiler warning
-Added new CheckParameters tests in SimulationTests and LatticeTests
-Updated various params definitions with the new parameter format
-Added new test to InitializationTests in LatticeTests to check for exception when trying to initialize a Lattice object with invalid params
-Added new test to SetupTests in SimulationTests to check for exception when trying to initialize a Simulation object with invalid params

CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+--------------------------------------------------------------------------------------------------------------------------------
+
+## [Unreleased]
+
+## [v2.0.0-rc.1] - 2018-12-08 - Release Candidate 1
+
+### Added
+- CONTRIBUTING.md - New file with instructions for how others can contribute to the project
+- README.md - Link to new CONTRIBUTING file
+- CHANGELOG.md - New file detailing the changes for each release
+- README.md - Link to new CHANGELOG file
+- README.md - More detailed instructions for building and testing KMC_Lattice
+- Object (calculateDisplacement) - New optional direction parameter that allows users to tell the function to calculate the displacement along a specific Cartesian direction
+- Simulation (getN_events) - Cast return of count_if function to int to prevent compiler warning
+- Utils (calculateProbabilityHist) - Float versions of several calculateProbabilityHist functions
+- Utils (calculateProbabilityHist) - Filtering of input data vectors to remove inf and nan entries
+- Utils (calculateProbabilityHist) - Check for and correct index calculation error due to floating point rounding
+- Utils (createExponentialDOSVector) - Float version of the createExponentialDOSVector function to allow the user to conserve memory
+- Utils (createGaussianDOSVector) - Float version of the createExponentialDOSVector function to allow the user to conserve memory
+- Utils (vector_which_median) - Cast return of distance function to int to prevent compiler warning
+- test.cpp (BKL_determinePathwayTests) - Cast return of count_if function to int to prevent compiler warning
+- test.cpp (CalculateProbabilityHistTests) - Tests of the float versions of calculateProbabilityHist
+- test.cpp (CalculateProbabilityHistTests) - Tests of both double and float versions of calculateProbabilityHist where the input data vectors contain some non finite entries
+= test.cpp (EventExecutionTests) - Cast return of count_if function to int to prevent compiler warning
+- test.cpp (ExponentialDOSTests) - Test of the float version of the createExponentialDOSVector
+- test.cpp (ExponentialDOSTests) - Cast return of count_if function to int to prevent compiler warning
+- test.cpp (GaussianDOSTests) - Test of the float version of the createGaussianDOSVector
+- test.cpp (LatticeTests) - Cast return of count_if functions to int to prevent compiler warning
+- test.cpp (ObjectTests) - Tests of the new calculateDisplacement function behavior
+
+
+### Changed
+- Doxyfile - Updated the version number to v2.0.0-rc.1
+- docs - Generated updated Doxygen documentation
+- Parameters_Lattice - Refactored struct into a new class
+- test.cpp (AlgorithmTests) - Increased N_tests to gather more statistics and reduce likelihood of test failure
+- Utils (createExponentialDOSVector) - Refactored code to make selection of the Gaussian side or the exponential side of the dist more simple
+- Utils (createGaussianDOSVector) - Refactored code to use generate function for filling the output data vector
+- Utils (MPI_*) - Refactored functions by replacing for loops with copy, assign, and accumulate functions to make code more concise
+- test.cpp (main) - Re-enabled command line output during the tests to make it easier to see when errors occur
+- test.cpp (CalculateProbabilityHistTests) - Replaced generic unform_real_distribution by specifying use of the double version
+- test.cpp (CalculateProbabilityHistTests) - Increasing the number of entries in the data vectors to increase statistical accuracy and reduce likelihood of test failure
+- test.cpp (CalculateProbabilityHistTests) - Refactored tests to use the generate function for filling a vector with random numbers
+
+### Fixed
+- Event - Corrected the copyright years in the Doxygen documentation block for the class
+- Lattice - Corrected the copyright years in the Doxygen documentation block for the class
+- Object - Corrected the copyright years in the Doxygen documentation block for the class
+- Simulation - Corrected the copyright years in the Doxygen documentation block for the class
+- Site - Corrected the copyright years in the Doxygen documentation block for the class

CONTRIBUTING.md

@@ -0,0 +1,96 @@
+# Contributing to KMC_Lattice
+
+We welcome new contributors to this project to help make the Ising_OPV morphology tool better and more effective for our scientific and educational users. Contributions can take on a variety of forms, such as bug reports, feature requests, code documentation updates, user tutorials, feature implementations, bugfixes, and more.
+
+## Ground Rules
+
+- To maintain an inclusive and welcoming environment, all community members must follow the [Code of Conduct](./CODE_OF_CONDUCT.md).
+- To keep project development organized, all new features and bugfixes must be proposed and discussed using [issues](https://github.com/MikeHeiber/KMC_Lattice/issues) before changes are implemented.
+- C++ code should follow the [C++11 standard](https://en.wikipedia.org/wiki/C%2B%2B11) and should be written to be simple and largely self-documenting with self-descriptive names.
+
+## Filing Issues
+
+One of the easiest ways to contribute is by using the software and submitting bug reports and feature requests as issues in the [Issues section](https://github.com/MikeHeiber/KMC_Lattice/issues). 
+Before filing a new issue please check that your issue has not already been submitted. 
+If it has, 'like' the issue and add any additional feedback you have to the issue thread in a comment.
+If your issue has not already been filed, create a new issue and provide a detailed description of the problem or new idea/suggestion. 
+The code owners will review new issues, provide feedback, and decide if and when to implement the changes needed to resolve the issue.
+
+## Working on an Issue
+
+1. Before you set out to tackle an issue, discuss your implementation plans with the code owners on the issue page.
+
+    Especially for code additions needed to add new features, it is important to discuss your implementation ideas with the code owners to ensure that the software design is relatively well thought out and fits with the rest of the codebase.
+
+2. Create fork of the KMC_Lattice repo on your account.
+
+    Click the "Fork" button near the top of any KMC_Lattice Github webpage.
+
+3. Connect your fork to the upstream repo
+
+    ```
+    git remote add upstream https://github.com/MikeHeiber/KMC_Lattice.git
+    ```
+
+4. Clone your forked KMC_Lattice repo to your local machine.
+
+    ```
+    git clone --recurse-submodules https://github.com/YOUR_USERNAME/KMC_Lattice
+    ```
+
+5. Create a new feature branch from the development branch.
+
+    ```
+    git checkout development
+    git branch feature-new-thing
+    git checkout feature-new-thing
+    ```
+
+6. Implement your changes keeping the scope of changes limited to the specified issue.
+
+7. Document your changes by adding to the [Changelog](./CHANGELOG.md).
+
+8. Update your new branch with any upstream changes and resolve any conflicts.
+
+    ```
+    git fetch upstream
+    git checkout development
+    git merge upstream/development
+    git checkout feature-new-thing
+    git rebase development
+    ```
+
+9. Make sure your changes do not break any of the existing functionality by running the tests locally.
+
+    ```
+    make test
+    ./test/KMC_Lattice_tests.exe
+    mpiexec -n 4 ./test/KMC_Lattice_MPI_tests.exe
+    ```
+    
+10. Push your local changes to your forked KMC_Lattice repo.
+
+    ```
+    git push origin feature-new-thing
+    ```
+
+11. Submit a pull request
+
+    See below for details about how to submit a pull request.
+
+## Code Testing and Documentation Standards
+
+Unit tests using the [googletest framework](https://github.com/abseil/googletest/blob/master/googletest/docs/primer.md) must be created for all new/modified functions and added to the test/test.cpp or test/test_mpi.cpp file as appropriate. Tests should include comments that describe what functionality each test code section is testing for.
+
+All new/modified classes and functions must be documented using the [Doxygen style](https://www.stack.nl/~dimitri/doxygen/manual/docblocks.html).
+
+## Submitting A Pull Request
+
+The pull request must reference the issue that is being resolved.
+Merging of feature branches into the development branch will be done using a squash merge operation to keep a tidy Git history.
+The squash merge will be done by a code owner, so you must provide a single overall commit message that details all changes in the pull request body text for the code owner the use with the merge.
+The pull request version of the code must pass all [TravisCI tests](https://travis-ci.org/MikeHeiber/KMC_Lattice) and must not reduce code testing coverage on [Coveralls](https://coveralls.io/github/MikeHeiber/KMC_Lattice).
+Code will be formatted during the code review stage to the Microsoft Visual Studio 2017 standard format.
+Updated documentation files will also be generated by Doxygen during the code review stage as needed.
+Code owners may add new commits to your pull request branch in order to help you fix any problems.
+

Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = KMC_Lattice
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = v2.0-beta.5
+PROJECT_NUMBER         = v2.0.0-rc.1
 
 # 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
@@ -435,7 +435,7 @@ LOOKUP_CACHE_SIZE      = 0
 # normally produced when WARNINGS is set to YES.
 # The default value is: NO.
 
-EXTRACT_ALL            = NO
+EXTRACT_ALL            = YES
 
 # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
 # be included in the documentation.
@@ -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\Github\KMC_Lattice\src
+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,8 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = 
+EXCLUDE                = googletest \
+                         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

@@ -17,9 +17,10 @@ For further reading about kinetic Monte Carlo simulations, nice overviews of the
 ## Current Status
 
 The current release is 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).
-Most major planned features that are to be included in v2.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/KMC_Lattice/issues) section. 
+All major planned features that are to be included in v2.0 are now implemented and have undergone significant testing. 
+Please report any remaining bugs or submit feature requests for future releases in the [Issues](https://github.com/MikeHeiber/KMC_Lattice/issues) section. 
+
+To keep track of upcoming changes or review prior changes to the codebase, please see the [Changelog](./CHANGELOG.md).
 
 #### Continuous Integration and Testing Status:
 
@@ -39,8 +40,9 @@ Code is being tested using [googletest](https://github.com/google/googletest) wi
 
 ## Contact
 
-If you would like to contribute to the development of this project or would like some help in building an efficient KMC simulation tool for your specific scientific problem, 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).
+If you would like to contribute to the development of this project, please see the [contributing instructions](./CONTRIBUTING.md).
+If you would like some help in using or customizing the tool for your research, please contact me ([email protected]) to discuss a collaboration. 
+You can check out my research using this tool and other work on [Researchgate](https://www.researchgate.net/profile/Michael_Heiber).
 
 ## How to try KMC_Lattice?
 
@@ -56,33 +58,58 @@ If you wish, you can also install MPI on your own personal workstation and then
 - MPICH, http://www.mpich.org/
 - MVAPICH, http://mvapich.cse.ohio-state.edu/
 
-Once you have an MPI library installed, to build the KMC_Lattice library, copy the KMC_Lattice directory to your machine, set it as your working directory, and run `make`. 
-Compilation flags have been set for the GCC and PGI compilers.  If you are using another compiler, you may need to edit the makefile and define your own compiler options.
-However, before you use the KMC_Lattice library, you should test it on your own hardware using the unit and system tests provided. 
-Build the testing executable by running `make test`. 
-Once the test build is complete, run `./test/KMC_Lattice_tests.exe`.
+Once you have an MPI library installed, to build KMC_Lattice, first copy the KMC_Lattice directory to your machine.  On Linux this can be done using the command,
+
+```git clone --recurse-submodules https://github.com/MikeHeiber/KMC_Lattice```
+
+Then set KMC_Lattice as your working directory,
+
+```cd KMC_Lattice```
+
+and finally build the software package with the default makefile.
+
+```make```
+
+In the default makefile, compilation flags have been set for the 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 KMC_Lattice 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, run the test executables.
+
+```./test/KMC_Lattice_tests.exe```
+
+and
+
+```mpiexeec -n 4 ./test/KMC_Lattice_MPI_tests.exe```
+
 Please report any build or testing errors in the [Issues](https://github.com/MikeHeiber/KMC_Lattice/issues) section. 
 
 ## Package Contents
 
+Event class - This base class can be extended to represent any process/mechanism/transition that one would like to simulate. 
+It could represent a hopping motion event, a reaction event, etc. depending on the application. 
+Typically, derived events are associated with a particular derived object. 
+The Event class contains the fundamental properties and back-end operations that any given state transition would require.
+
+Lattice class - This class implements a lattice, its boundary conditions, and keeps track of its occupancy.
+
 Object class - This base class can be extended to represent any entity that one would like to simulate. 
 It could represent an electron, atom, molecule, organism, etc. depending on the application. 
 The Object class contains the fundamental properties and back-end operations that any given entity simulation would require.
 
-Lattice class - This class implements a lattice, its boundary conditions, and keeps track of its occupancy.
+Parameters_Lattice class - This class contains all of the parameters needed to construct a Lattice object.
 
-Event class - This base class can be extended to represent any process/mechanism/transition that one would like to simulate. 
-It could represent a hopping motion event, a reaction event, etc. depending on the application. 
-Typically, derived events are associated with a particular derived object. 
-The Event class contains the fundamental properties and back-end operations that any given state transition would require.
+Parameters_Simulation class - This class contains all of the parameters needed to construct a Simulation object.
+
+Simulation class - This base class can be extended to manage all derived objects and their associated events. 
+The Simulation class contains the fundamental properties and back-end operations that most simulations would require.
 
 Site class - This base class can be extended to represent the lattice sites that make up the simulation medium/environment. 
 Added site properties can be used to implement interactions between the simulation environment and the objects, which then affect the events. 
 For example, site energies can be assigned to derived site classes to account for inhomogeneous systems.
 
-Simulation class - This base class can be extended to manage all derived objects and their associated events. 
-The Simulation class contains the fundamental properties and back-end operations that most simulations would require.
-
 Utils - This file contains a number of useful utility functions, scientific constants, etc. that can then be used throughout the software package.
 
 Version class - This class stores a valid software version string and has version comparison operators and can be used to compare different versions of things to check for compatibility.