How To Contribute A Project

Step I: Administrative Preliminaries
Please follow the following guidelines in preparation of your contribution to the PhysBAM code collection

  1. Check that your project is relevant and within the scope of PhysBAM - Contact Ron Fedkiw and check that the project you intend to contribute is within the scope of PhysBAM. For sub-projects, contact the individual project lead(s).
  2. Add your contribution as a stand-alone project - The simplest way to contribute a project is as a stand-alone code tree, one that does not have to link anywhere outside its root directory (which should be a subdirectory of the Projects folder).
  3. Provide a README file - Make sure to include this in your project directory, with instructions on which compiler and/or build system to use, which operating systems your code is compatible with, which system libraries should be installed for your project to run. Also provide information on how to run your executable, and how the contributor can be contacted.

Step II: Top level code organization
The simplest, yet very useful, part of the integration process has to do with separating parts of your code that naturally belong to the different top-level subdirectories. This level addresses code permissions, common tools, etc. Important: DO NOT check any non-BSD code into Public Library. The directories are:

  1. Projects: This is a mishmash of permissions and may contain code and data that others do not have permission to use. Thus, shrinking the amount of code in the project directory to some degree helps both the user and the contributor save time, and is the purpose of the top level directory structure. A good goal would be to make your entire project covered under a BSD, but this is not required and may take some time.
  2. External Libraries: This is where industry code, licensed code, or questionable code should go - including complied binaries. An important aspect of the external libraries is that they belong to another entity and are provided only for completeness. A user is responsible for ascertaining whether or not they are allowed to use this code and in what form from the external entity. This sub-tree can also serve as placeholder for proprietary software necessary for certain project, but which will not be distributed with PhysBAM.
  3. Personal Libraries: This is code you or your institution retains ownership of. As opposed to an external library where one needs to contact the external entity, it is assumed that the code in your personal library can be accessed in one form or another by speaking with you directly. Obviously you will not have a personal library when you first get involved with the project so you need to create one.
  4. Scripts & Tools: Code in here started out in personal libraries, and eventually migrated to these directories as they became utilized by a number of users.
  5. Public_Data: This is a repository for shared data sets. Since data can be so immense, it has been split out from the rest of the library so people can maintain repositories without the data in it.
  6. Public_Library: All code here MUST be under a BSD license. See step III below.

Step III: Pursue a greater degree of integration with core PhysBAM

  1. Reasons for tighter integration - Although a stand-alone contribution can be useful, this utility will be maximized by leveraging the collective strength of different projects and PhysBAM components. For example, a simulation project can leverage the functionality of a rendering or visualization tool, contributed by a different group. Or employ the mesh-generation features of another project in PhysBAM. The core PhysBAM library also includes a number of standard numerical algorithms and simulation primitives, many of which come with parallel implementations, which could also provide convenience and acceleration to a client project.
  2. Coordinate I/O - Even if no explicit code integration is pursued, adopting common I/O conventions and file formats will greatly facilitate interoperability of different projects. Built-in PhysBAM file formats can be useful in this regard, providing I/O conventions for a diverse spectrum of data, from primitive data types to complex simulation scenes. Whenever different file formats have to be maintained, consider providing conversion utilities.
  3. Coordinate Data Structures - For a tighter interoperability of code across projects, along with the ability to combine two projects or encapsulate one into the other, a contributor may choose to pursue a greater degree of compliance with PhysBAM data structures, classes and algorithms.
  4. Leverage Existing Code - The core PhysBAM library includes a number of algorithmic kernels, which have been field-tested in many projects and within several demanding production environments. Project contributors may opt to leverage some of this existing code in order to optimize, generalize or accelerate their development.