Merge pull request #14 from espottesmith/contributions

Documentation: Guide for contributors

Expanding.md

@@ -0,0 +1,38 @@
+# Adding Simulators to RNMC
+
+`RNMC` is designed to be modular. Individual types of simulations all draw from a small `core` library, but most of their logic is independent. This means that, to develop a new type of simulation, you do not need to have a deep understanding of every component of `RNMC`. As long as you understand `core` and the general structure of a new simulation type, you're free to do what you want!
+
+Here, we describe the structure of `RNMC`, explaining the components of the `core` library and what goes into a simulator in order to help facilitate the development of new simulators.
+
+## The Core Library
+
+The `core` library contains resources that are shared by just about every simulator in `RNMC`. New simulators may require small modifications to `core`, but it also may be possible for you to develop a new simulator without changing anything!
+
+`core` contains:
+
+- `RNMC_types.h`: Commonly used datatypes for simulations.
+- `sql.h`: An interface to read from and write to SQLite3 database files.
+- `sql_types.h` / `sql_types.cpp`: Specific datatypes for interacting with types of tables and data that are commonly used by `RNMC` simulators. Examples include the `initial_state` table (defining what the initial simulation looks like, in terms of numbers of each species) and `metadata` table (defining how many different species and reactions are in the simulation).
+- `sampler.h`: A wrapper over `GSL` random number generators, used for random sampling.
+- `queues.h`: Queues for parallel operation, ensuring that different processes do not attempt to run simulations on the same seed and that history data is safely added to the trajectory database.
+- `simulation.h` / `simulation.cpp`: Defines a core interface to execute steps with either a time or number-of-steps cutoff. Simulations on a lattice behave somewhat differently and are defined in `lattice_simulation.h` and `lattice_simultion.cpp`.
+- `simulator_payload.h`: A layer above the simulation interface that initializes simulations, executes them, and then logs their outputs to a history queue to be inserted into a database.
+- `dispatcher.h` / `dispatcher.cpp`: Defines a `Dispatcher` that manages different simulating processes.
+
+The `core` folder also defines the high-level interfaces for each type of simulator. For instance, `nano_particle_simulation.h`/`nano_particle_simulation.cpp` defines the interface for `NPMC`.
+
+## Components of a Simulator
+
+Different simulators may have different levels of complexity and require different components. Generally, though, `RNMC` simulations have similar components. These include:
+- Additional types for SQLite3 input and output
+- Additional non-SQL datatypes
+- "Solvers", which use the Sampler interface defined in `core/sampler.h` to select events (see *e.g.*, `GMC/linear_solver.h` and `GMC/linear_solver.cpp` for a simple example).
+- A "reaction network" class. These classes are expected to manage:
+    - Initializing the simulation state by reading from an appropriate SQLite table
+    - Updating the state and event propensities based on an event selected by a Solver through the simulation interface
+    - Checkpointing simulations
+    - Creating history elements to write to a SQLite database
+- A command-line interface for simulations. In general, we prefer to define simulation parameters using command-line arguments, but, depending on the complexity of the simulation inputs, reading parameters from a configuration file may also be appropriate.
+- A makefile for compiling the simulation executable.
+
+Other than the main simulation interface mentioned above (which is housed in `core`) and testing code (housed in `tests`), all application-specific code should be placed in a separate directory (*e.g.*, `NPMC` or `GMC`). For a more detailed understanding of how `RNMC` is organized, we encourage you to select an existing type of simulation (*e.g.*, `GMC`) and read through the source code.

_layouts/default.html

@@ -66,6 +66,7 @@ <h1><a href="{{ "/" | absolute_url }}">{{ site.title | default: site.github.repo
           <li class="TOC"><a class="TOC" href="LGMC.html" class="active"></i>LGMC</a></li>
           <li class="TOC"><a class="TOC" href="Testing.html" class="active"></i>Testing</a></li>
           <li class="TOC"><a class="TOC" href="Examples.html" class="active"></i>Examples</a></li>
+          <li class="TOC"><a class="TOC" href="Contributors.html" class=active"></i>Contributing to RNMC</a></li>
         </ul>
 
         </body>

contributors.md

@@ -0,0 +1,73 @@
+# Guide for Developers and Contributors
+
+## Getting Started
+
+1. If you don't already have one, create and set up a free [GitHub account](https://github.com).
+2. Install `git` on your local system, if it isn't already there.
+3. Fork `RNMC`. Go to [the RNMC GitHub page](https://github.com/BlauGroup/RNMC) and select "Fork". This will create a copy of the repository that you own and control.
+4. Copy the source code to your local system:
+
+```
+$ git clone https://github.com/<USERNAME>/RNMC
+```
+
+This will create a directory called "RNMC".
+
+## Adding New Features
+
+1. Make a new branch:
+
+```
+$ git pull  # Get most up-to-date code
+$ git checkout -b <BRANCH_NAME>  # Create new branch and switch to it
+```
+
+2. Add the main repository as a remote:
+
+```
+$ git remote add upstream https://github.com/BlauGroup/RNMC
+```
+
+3. Code! Make commits frequently to save your progress, and push to sync your local changes to GitHub. The first time, you'll need to set an origin:
+
+```
+$ git push --set-upstream origin <BRANCH_NAME> 
+```
+
+4. When you're ready, create a [pull request](https://github.com/BlauGroup/RNMC/pulls) on GitHub. “Work-in-progress” pull requests are encouraged, especially if this is your first time contributing to `RNMC`. If your feature is not finished, or you anticipate needing significant feedback/revisions before the PR is merged in, put "\[WIP\]" in the pull request title.
+
+## Raising Issues
+
+If you have a problem installing or using `RNMC`, you can raise an issue on our [GitHub page](https://github.com/BlauGroup/RNMC/issues). The issues page is also an appropriate place to ask questions or to suggest a new feature. If you create an issue, you can label it (e.g., "bug", "enhancement", or "question") to help us triage appropriately.
+
+## Your First Contribution
+
+If you have a feature that you want to add but don't know where to start: reach out to [Sam Blau](mailto:[email protected]) and describe what you have in mind. He, or one of the developers, may be able to help you get started.
+
+If you're specifically interested in adding a new type of simulator to RNMC: check back our guide to [expanding RNMC](./Expanding.md), which details the basic components that you'll need to create a simulator.
+
+If you want to help but don't have a particular idea in mind, check out the issues page and see if there's something that you would be interested in contributing.
+
+## Coding Guidelines and Style
+
+### Versions
+
+`RNMC` is written in C++17. Before opening a pull request, please ensure that all modifications and additions are consistent with this version.
+
+### Dependencies
+
+`RNMC` is a relatively slim codebase with only two external dependencies: `sqlite3` and `GSL`. We encourage you to only use the C/C++ standard library and these existing dependencies and to avoid adding additional dependencies. If you believe that an external dependency is necessary, please discuss this with the `RNMC` developers and maintainers.
+
+### Documentation
+
+We do not require documentation on a per-file or per-function basis but encourage comments that explain the steps involved in different processes. If you add new features, we may request additional code documentation to assist with maintainability.
+
+New features (and especially new simulators!) should be described in the repository README and in the documentation hosted on [GitHub Pages](https://blaugroup.github.io/RNMC/). Note that information for GitHub pages is located in the `gh-pages` branch of the `RNMC` repository, so any PRs to add documentation to our project website should modify and merge into `gh-pages`, rather than `main`.
+
+### Testing
+
+We test `RNMC` in two ways: unit tests and end-to-end tests. Unit tests evaluate discrete parts of the code base with self-contained examples. They're especially helpful for debugging. End-to-end tests perform full simulations (typically on small and simple systems) that ensure that the output of a simulation is correct, typically referencing some human-verified baseline results.
+
+All new features must have unit tests. New simulators are encouraged to have end-to-end tests. These are not required if the simulators have strong non-deterministic behavior that make end-to-end correctness or consistency checking challenging (as is the case for certain simulations using `LGMC`).
+
+See the [testing page](./Testing.md) for more detail about our testing suite.

index.md

@@ -5,3 +5,8 @@ Reaction Network Monte Carlo (`RNMC`) is a collection of programs for kinetic Mo
 - `GMC` - [Gillespie Monte Carlo](./GMC.md): Implementation of Gillespie's next reaction simulator. `GMC` is able to run simulations of reaction networks with hundreds of millions of reactions.
 - `NPMC` - [Nano Particle Monte Carlo](./NPMC.md): A three dimensional statistical field theory simulator which supports one- and two-site interactions. `NPMC` is useful for simulating nano particles.
 - `LGMC` - [Lattice Gillespie Monte Carlo](./NPMC.md): A kMC implementation coupling a homogeneous (Gillespie-like) region with a lattice, enabling simulations with reactions occurring in multiple phases and capable of electrochemical reactions.
+
+## Contributing
+RNMC is hosted on [GitHub](https://github.com/BlauGroup/RNMC). Users are encouraged to fork the repository and submit features via pull request. You can also suggest features and document bugs through the [issues page](https://github.com/BlauGroup/RNMC/issues).
+
+Additional details for contributors are provided on our [guide to contributors](./Contributors.md).