Contribute test cases and example applications

Users who wish to share example applications and test cases they realized using the OpenQBMM solvers are welcome to use the designated git repository for this type of contribution, as explained below.

Pre-requisite for the contribution of test cases

  1. Users willing 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. Test cases and example applications should be, for what possible, of general interest.
  4. The test case has to be self-contained. In particular, it must be possible to execute the test case with a standard installation of OpenFOAM and OpenQBMM. Test cases which require external software will not be accepted.
  5. Only the files required to execute the test case 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 a test case for submission below for additional details.

How to prepare a test case for submission

Test cases are supposed to work out of the box, simply executing the standard sequence of commands

  • blockMesh
  • setFields (if initialization is needed)
  • decomposePar (if parallel run is needed)
  • solver command

In case the command sequence is more complex than what indicate above, a bash script caled Allrun must be provided, as clarified below.

Before submitting a test case or an example application, the following steps should be followed:

  1. Assign a representative name to the directory containing the test case. A specific name is preferred, because different contributors may work on similar applications. For example, if your test case demonstrates the solution of a population balance equation in a chemical reactor for the precipitation of barium sulfate, it would be advisable to use a name like bariumSulfatePBE, rather than reactorPBE. Names should follow the back camel convention, as shown in the previous examples.
  2. If your case requires non-uniform initial conditions, provide the setFieldDict rather than the initialized fields, in order to limit the size of the test case. If the initial condition cannot be set with setFieldDict, providing the initialized fields is acceptable.
  3. If the mesh is generated using blockMesh, please only provide the blockMeshDict and eventually the boundary file. Do not provide the other mesh files.
  4. If the mesh is generated using snappyHexMesh or foamyHexMesh, please provide the corresponding dictionary and the STL/OBJ files.
  5. Please provide two bash scripts to automate the execution of the test case and the cleanup of its directory
    • A bash script called Allrun, which should contain the sequence of commands that are required to execute the test case.
    • A bash script called Allclean, which should remove all the files that were generated during the execution of the test case, effectively resetting it to the initial state.
  6. Add a README file in the main directory of the test case 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 Cases 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:YourGithubUserName/Contributed-Cases.git
  5. Add the test case 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-Cases 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.