Contribute code

Users who wish to contribute code to OpenQBMM solvers are welcome to use the designated git repository for this type of contribution, as explained in this page.

Pre-requisite for the contribution of code

  1. Users who want to contribute must ensure they are the original authors of the contribution, and they have the right to share the material they are contributing.
  2. Contributions will be accepted only if licensed under the GNU General Public License 3.
  3. Code contributions should follow the coding style of OpenQBMM and OpenFOAM, avoiding code repetition and using the proper indentation.
  4. Code contributions should be of general interest, and generally integrated into the OpenQBMM solvers.
  5. The contributed code must compile against a standard installation of OpenFOAM and OpenQBMM.
  6. Only the files required to compile the contributed code should be provided. Any additional file not strictly necessary to the execution of the provided test case should be removed. Please, refer to How to prepare code for submission below for additional details.

How to prepare code for submission

Code contributed to the OpenQBMM project must build with the standard wmake command provided by OpenFOAM. In case the build process for the contributed code requires multiple steps, a bash script called Allwmake must be provided in the top directory containing the code.

Before submitting code, the following steps should be followed:

  1. Ensure that the contributed code contains appropriate headers in each file. Please, use the provided templates.
  2. Ensure that the header of each file contains licensing and copyright information.
  3. Assign a representative name to the directory containing the code. A specific name is preferred, because different contributors may work on similar applications. For example, if the code provides a post-processing utility for a PBE solver to calculate the reconstructed particle-size distribution, reconstructSizeDistributionPBE is an appropriate name.
  4. If the contributed code requires more than a simple wmake command to be built, please provide two bash scripts to automate the build and cleanup process:
    • A bash script called Allwmake, which should contain the sequence of commands that are required to execute the test case.
    • A bash script called Allwclean, which should remove all the files that were generated during the build process, effectively resetting it to the initial state.
  5. Add a README file in the main directory of the contributed code with your name, affiliation, and a brief description of the test case.

How to submit a test case

In order to contribute a test case or an example application, contributors need to create a free github account and follow these steps:

  1. Log into GitHub.
  2. Go to the OpenQBMM Contributed Code repository.
  3. Click on the Fork button.
  4. Clone the forked git repository from the contributor’s account (YourGithubUserName must be replaced with the actual contributor user name on GitHub.
    • git clone git@github.com:OpenQBMM/Contributed-Code.git
  5. Add the code you want to contribute to the directory corresponding to the OpenQBMM solver required to run the test case.
  6. Add the test case to the git repository using the git add command:
    • git add /path/to/test/case/top/directory
  7. Commit your changes to the local copy of the git repository
    • git commit -m “Added case <putCaseNameHere>”
  8. Push your changes to the repository on GitHub (Warning: this step will make your contribution public and visible to anybody on the Internet)
    • git push
  9. Issue a Pull request to the Contributed-Cases repository on GitHub.
  10. The developers of the OpenQBMM suite of solvers will review your contribution and verify it satisfies the requirements described above. In case the requirements are satisfied, the contribution will be accepted, and made available through the OpenQBMM Contributed-Code repository on GitHub. If a contribution is accepted, the name of the contributor will be added to the list of contributors. It is advisable to use an appropriate name and email when submitting the contribution, in order to ensure proper recognition.