How To Contribute A Project
Step I: Administrative Preliminaries
Please follow the following guidelines in preparation of your contribution to
the PhysBAM code collection
- 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).
- 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).
- 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
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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
- 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.
- 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.
- 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
- 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.