Merge pull request #51 from jtebert/julia/docs

Add additional documentation and license

Author: jtebert

CONTRIBUTORS.md

@@ -0,0 +1,11 @@
+# Contributors
+
+[Julia Ebert](https://juliaebert.com) ([@jtebert](https://github.com/jtebert)): Primary developer and maintainer
+
+[Richard Barnes](http://rbarnes.org/) ([@r-barnes](https://github.com/r-barnes)): Parallelization, optimization, CMake, and structural improvements
+
+[Michael Rubenstein](http://users.eecs.northwestern.edu/~mrubenst/) ([@morning-light-mountain](https://github.com/morning-light-mountain)): Created initial Kilobot simulator from which this simulator is derived
+
+German Espinosa ([@germanespinosa](https://github.com/germanespinosa)): Contributed to initial Kilobot simulator from which this simulator is derived
+
+Gabriel Seymour ([@SeymourGabe](https://github.com/SeymourGabe)): Beta testing, noisy light detection, and battery life bug fix

LICENSE

@@ -0,0 +1,7 @@
+Copyright 2019 Kilosim CONTRIBUTORS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,27 +1,35 @@
-# Kilosim: Kilobot Simulator
+# ![Kilosim logo](docs/logo.svg) Kilosim: Kilobot Simulator
 
 [![Build Status](https://travis-ci.com/jtebert/kilosim.svg?token=s6ZVW1bvfNjgbZQh2x9M&branch=master)](https://travis-ci.com/jtebert/kilosim)
+[![GitHub Issues](https://img.shields.io/github/issues/jtebert/kilosim.svg)](https://github.com/jtebert/kilosim/issues)
+[![GitHub release](https://img.shields.io/github/release-pre/jtebert/kilosim?color=yellow)](https://github.com/jtebert/kilosim/releases)
 
 This is maintained on GitHub in the [kilosim repository](https://github.com/jtebert/kilosim). You can [submit any issues or questions here](https://github.com/jtebert/kilosim/issues).
 
-[__Full Documentation__](https://jtebert.github.io/kilosim/index.html)
+[**Full Documentation**](https://jtebert.github.io/kilosim/index.html)
 
 ---
 
-Kilosim is designed to be a fast, lightweight, pseudo-physical* simulator for Kilobots. Notable benefits include:
+Kilosim is a fast, lightweight, pseudo-physical* C++ simulator for Kilobot robots. Notable benefits include:
 
 - Pseudo-physical model means fast simulation for high-throughput
-- Directly use code written for Kilobots, using the same Kilolib API
-- Included Logger to easily to save experiment parameters in log continuous state data
+- Easily re-use code written for Kilobots, using the same Kilolib API
 - Includes support for ambient light sensing
-- Cross-platform Viewer for debugging and recording simulations
-- [In progress] Parallelized with OpenMP (run a 100-minute, 800 robot simulation in about 10 seconds)
-- Easy configuration with JSON files to run multiple and varied experiments
+- Included `Logger` to easily to save experiment parameters in log continuous state data
+- Cross-platform `Viewer` for debugging and recording simulations
+- Easy configuration with JSON files to run multiple trials and varied experiments
+- *[In progress]* Parallelization with OpenMP
 
-*\* Pseudo-physical means that it is spatial and handles issues like collisions in a functional but hand-wavy manner. We make no attempt to accurately model true physical interactions. If you want to see what this means, run an example simulation with the Viewer.*
+\* *Pseudo-physical means that it is spatial and handles issues like collisions in a functional but hand-wavy manner. We make no attempt to accurately model true physical interactions. If you want to see what this means, run an example simulation with the Viewer.*
+
+Note that this project is currently in a pre-release state and may still contain bugs, incomplete documentation, and missing features. If you have issues using the code, contact the developers or [open an issue](https://github.com/jtebert/kilosim/issues/new).
 
 ## Installing and Using
 
+**NOTE:** At this time, we only support Kilosim on Linux. Other operating systems will be supported by a full release.
+
+You can either [clone the repository from GitHub](https://github.com/jtebert/kilosim) or [download the latest release](https://github.com/jtebert/kilosim/releases).
+
 ### Dependencies
 
 [HDF5](https://portal.hdfgroup.org/display/HDF5/HDF5), [SFML](https://www.sfml-dev.org/index.php), and [OpenMP](https://www.openmp.org/). Install on Ubuntu-like systems with: `sudo apt install libsfml-dev libhdf5-dev libomp-dev`
@@ -49,22 +57,46 @@ Run the executable generated by `make exec`
 
     ./bin/kilosim
 
-### Build Documentation
+### Using static library
 
-Build the HTML documentation: (Requires Doxygen to be installed.)
+**TODO:** Write tutorial on linking to static library
 
-    doxygen
-
-This will automatically use the settings in `Doxyfile` and save the results to `docs/`. (The latest full documentation is automatically generated and published [here](https://jtebert.github.io/kilosim/index.html).)
 
 ## Configuration and Parameters
 
 Configuration files are defined as JSON files and can be loaded with a ConfigParser. The contents of flat JSON files can be automatically saved with your data using the Logger. (Support for saving JSON objects and arrays to HDF5 may be added in the future if someone needs/wants it.)
 
 There are no fixed requirements for the contents of the configuration files; it's an un-opinionated convenience tool for importing and using whatever (atomic) parameters you want.
 
+## Support
+
+If you are having issues installing or using the simulator, [open an issue](https://github.com/jtebert/kilosim/issues/new) or [email Julia](mailto:julia@juliaebert.com).
+
+### Known Issues
+
+- Fails with GCC 8 (We suspect this is a GCC bug; see [issue #23](https://github.com/jtebert/kilosim/issues/23).) **Workaround:** Change your GCC version.
+- Viewer does not work over SSH
+
+## Contributing
+
+We welcome contributions to the repository. To find things we're currently looking for help with, [check out the open issues](https://github.com/jtebert/kilosim/issues?utf8=✓&q=is%3Aissue+is%3Aopen+).
+
+If you discover a bug or have an idea, for an improvement, [open an issue](https://github.com/jtebert/kilosim/issues/new).
+
+If you add something you think would be useful to others, submit a pull request. All code should be [fully documented](http://www.doxygen.nl/manual/docblocks.html). You can check your documentation by [building the documentation locally](#build-documentation) Code reviews will be required for all pull requests, but we currently do not perform unit testing.
+
+See a [full list of the contributors and their contributions here](CONTRIBUTORS.md).
+
+### Build Documentation
+
+Build the HTML documentation: (Requires Doxygen to be installed.)
+
+    doxygen
+
+This will automatically use the settings in `Doxyfile` and save the results to `docs/`. (The latest full documentation is automatically generated and published [here](https://jtebert.github.io/kilosim/index.html).)
+
 ## License
 
-**TBD**
+This software is released under the [MIT License](LICENSE).
 
-This shouldn't be publicly used or shared until a license has been set for this software.
+If you use this software for a publication, please cite it.